|
@@ -1,11 +1,208 @@
|
|
|
import { SourceCode } from '@theme';
|
|
import { SourceCode } from '@theme';
|
|
|
|
|
+import { BasicStory } from 'components/form-materials/components/condition-context';
|
|
|
|
|
+
|
|
|
|
|
+# ConditionContext
|
|
|
|
|
+
|
|
|
|
|
+ConditionContext is a context management system for condition configuration, used to uniformly manage condition rules and operator configurations, providing a consistent configuration environment for condition components.
|
|
|
|
|
+
|
|
|
|
|
+:::tip
|
|
|
|
|
+
|
|
|
|
|
+The condition configuration context of ConditionContext can affect the following materials:
|
|
|
|
|
+
|
|
|
|
|
+- [**ConditionRow**](./condition-row)
|
|
|
|
|
+- [**DBConditionRow**](./db-condition-row)
|
|
|
|
|
|
|
|
-:::warning
|
|
|
|
|
-The material has been developed and the documentation is still being improved. Contributions are welcome.
|
|
|
|
|
:::
|
|
:::
|
|
|
|
|
|
|
|
-# ConditionContext (WIP)
|
|
|
|
|
|
|
+## Examples
|
|
|
|
|
+
|
|
|
|
|
+### Basic Usage
|
|
|
|
|
+
|
|
|
|
|
+<BasicStory />
|
|
|
|
|
+
|
|
|
|
|
+```tsx pure title="form-meta.tsx"
|
|
|
|
|
+import React from 'react';
|
|
|
|
|
+import { Field } from '@flowgram.ai/free-layout-editor';
|
|
|
|
|
+import {
|
|
|
|
|
+ ConditionProvider,
|
|
|
|
|
+ ConditionRow,
|
|
|
|
|
+ DBConditionRow,
|
|
|
|
|
+ type ConditionOpConfigs,
|
|
|
|
|
+ type IConditionRule
|
|
|
|
|
+} from '@flowgram.ai/form-materials';
|
|
|
|
|
+
|
|
|
|
|
+const OPS: ConditionOpConfigs = {
|
|
|
|
|
+ cop: {
|
|
|
|
|
+ abbreviation: 'C',
|
|
|
|
|
+ label: 'Custom Operator',
|
|
|
|
|
+ },
|
|
|
|
|
+};
|
|
|
|
|
+
|
|
|
|
|
+const RULES: Record<string, IConditionRule> = {
|
|
|
|
|
+ string: {
|
|
|
|
|
+ cop: { type: 'string' },
|
|
|
|
|
+ },
|
|
|
|
|
+};
|
|
|
|
|
+
|
|
|
|
|
+const formMeta = {
|
|
|
|
|
+ render: () => (
|
|
|
|
|
+ <>
|
|
|
|
|
+ <FormHeader />
|
|
|
|
|
+ <ConditionProvider ops={OPS} rules={RULES}>
|
|
|
|
|
+ <Field<any | undefined> name="condition_row">
|
|
|
|
|
+ {({ field }) => (
|
|
|
|
|
+ <ConditionRow value={field.value} onChange={(value) => field.onChange(value)} />
|
|
|
|
|
+ )}
|
|
|
|
|
+ </Field>
|
|
|
|
|
+ <Field<any | undefined> name="db_condition_row">
|
|
|
|
|
+ {({ field }) => (
|
|
|
|
|
+ <DBConditionRow
|
|
|
|
|
+ options={[
|
|
|
|
|
+ {
|
|
|
|
|
+ label: 'UserName',
|
|
|
|
|
+ value: 'username',
|
|
|
|
|
+ schema: { type: 'string' },
|
|
|
|
|
+ },
|
|
|
|
|
+ ]}
|
|
|
|
|
+ value={field.value}
|
|
|
|
|
+ onChange={(value) => field.onChange(value)}
|
|
|
|
|
+ />
|
|
|
|
|
+ )}
|
|
|
|
|
+ </Field>
|
|
|
|
|
+ </ConditionProvider>
|
|
|
|
|
+ </>
|
|
|
|
|
+ ),
|
|
|
|
|
+};
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## API Reference
|
|
|
|
|
+
|
|
|
|
|
+### ConditionProvider
|
|
|
|
|
+
|
|
|
|
|
+A context provider component for condition configuration, used to uniformly manage condition rules and operator configurations.
|
|
|
|
|
+
|
|
|
|
|
+| Parameter | Type | Required | Description |
|
|
|
|
|
+|-----------|------|----------|-------------|
|
|
|
|
|
+| `rules` | `Record<string, IConditionRule>` | No | Condition rule configuration |
|
|
|
|
|
+| `ops` | `ConditionOpConfigs` | No | Operator configuration |
|
|
|
|
|
+| `children` | `React.ReactNode` | Yes | Child components |
|
|
|
|
|
+
|
|
|
|
|
+### useCondition
|
|
|
|
|
+
|
|
|
|
|
+A hook to get condition configuration, which obtains corresponding configuration information based on data type and operator.
|
|
|
|
|
+
|
|
|
|
|
+For specific usage, you can refer to the use of `useCondition` in [ConditionRow's source code](https://github.com/bytedance/flowgram.ai/blob/main/packages/materials/form-materials/src/components/condition-row/index.tsx).
|
|
|
|
|
+
|
|
|
|
|
+### ConditionPresetOp
|
|
|
|
|
+
|
|
|
|
|
+A preset operator enumeration, providing commonly used comparison operators.
|
|
|
|
|
+
|
|
|
|
|
+| Enum Value | Description | Abbreviation |
|
|
|
|
|
+|------------|-------------|--------------|
|
|
|
|
|
+| `EQ` | Equal | `=` |
|
|
|
|
|
+| `NEQ` | Not Equal | `≠` |
|
|
|
|
|
+| `GT` | Greater Than | `>` |
|
|
|
|
|
+| `GTE` | Greater Than or Equal | `>=` |
|
|
|
|
|
+| `LT` | Less Than | `<` |
|
|
|
|
|
+| `LTE` | Less Than or Equal | `<=` |
|
|
|
|
|
+| `IN` | In | `∈` |
|
|
|
|
|
+| `NIN` | Not In | `∉` |
|
|
|
|
|
+| `CONTAINS` | Contains | `⊇` |
|
|
|
|
|
+| `NOT_CONTAINS` | Not Contains | `⊉` |
|
|
|
|
|
+| `IS_EMPTY` | Is Empty | `=` |
|
|
|
|
|
+| `IS_NOT_EMPTY` | Is Not Empty | `≠` |
|
|
|
|
|
+| `IS_TRUE` | Is True | `=` |
|
|
|
|
|
+| `IS_FALSE` | Is False | `=` |
|
|
|
|
|
+
|
|
|
|
|
+### Type Definitions
|
|
|
|
|
+
|
|
|
|
|
+```typescript
|
|
|
|
|
+// Operator configuration
|
|
|
|
|
+interface ConditionOpConfig {
|
|
|
|
|
+ label: string; // Operator label
|
|
|
|
|
+ abbreviation: string; // Operator abbreviation
|
|
|
|
|
+ rightDisplay?: string; // Right side display text (when right side is not a value)
|
|
|
|
|
+}
|
|
|
|
|
+
|
|
|
|
|
+// Operator configuration collection
|
|
|
|
|
+type ConditionOpConfigs = Record<string, ConditionOpConfig>;
|
|
|
|
|
+
|
|
|
|
|
+// Condition rule
|
|
|
|
|
+type IConditionRule = Record<string, string | IJsonSchema | null>;
|
|
|
|
|
+
|
|
|
|
|
+// Condition rule factory function
|
|
|
|
|
+type IConditionRuleFactory = (
|
|
|
|
|
+ schema?: IJsonSchema
|
|
|
|
|
+) => Record<string, string | IJsonSchema | null>;
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## Source Code Guide
|
|
|
|
|
|
|
|
<SourceCode
|
|
<SourceCode
|
|
|
href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/components/condition-context"
|
|
href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/components/condition-context"
|
|
|
-/>
|
|
|
|
|
|
|
+/>
|
|
|
|
|
+
|
|
|
|
|
+You can copy the source code to your local machine using the CLI command:
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+npx @flowgram.ai/cli@latest materials components/condition-context
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### Directory Structure
|
|
|
|
|
+
|
|
|
|
|
+```
|
|
|
|
|
+condition-context/
|
|
|
|
|
+├── context.tsx # Context implementation
|
|
|
|
|
+├── hooks/ # Hook functions directory
|
|
|
|
|
+│ └── use-condition.tsx # useCondition hook implementation
|
|
|
|
|
+├── index.tsx # Unified export file
|
|
|
|
|
+├── op.ts # Preset operator definitions
|
|
|
|
|
+└── types.ts # Type definitions
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### Core Implementation
|
|
|
|
|
+
|
|
|
|
|
+#### ConditionContext Workflow
|
|
|
|
|
+
|
|
|
|
|
+Here is the sequence diagram of the workflow for ConditionProvider and useCondition Hook:
|
|
|
|
|
+
|
|
|
|
|
+```mermaid
|
|
|
|
|
+sequenceDiagram
|
|
|
|
|
+ participant App as Application Component
|
|
|
|
|
+ participant Provider as ConditionProvider
|
|
|
|
|
+ participant Context as ConditionContext
|
|
|
|
|
+ participant Child as ConditionRow or DBConditionRow
|
|
|
|
|
+ participant Hook as useCondition Hook
|
|
|
|
|
+ participant TypeManager as useTypeManager
|
|
|
|
|
+
|
|
|
|
|
+ %% Initialization Phase
|
|
|
|
|
+ App->>Provider: Pass rules and ops configurations
|
|
|
|
|
+ Provider->>Context: Create Context and set default values
|
|
|
|
|
+ Provider->>Provider: Receive rules and ops parameters
|
|
|
|
|
+ Provider->>Context: Update configurations in Context
|
|
|
|
|
+ Provider-->>App: Render child components
|
|
|
|
|
+
|
|
|
|
|
+ %% Usage Phase
|
|
|
|
|
+ Child->>Hook: Call useCondition
|
|
|
|
|
+ Hook->>Context: Get configurations via useConditionContext()
|
|
|
|
|
+ Hook->>TypeManager: Get type manager
|
|
|
|
|
+ Hook->>Hook: Merge user rules and context rules
|
|
|
|
|
+ Hook->>Hook: Merge user operators and context operators
|
|
|
|
|
+ Hook->>TypeManager: Get type configuration based on leftSchema
|
|
|
|
|
+ Hook->>Hook: Calculate condition rules for current type
|
|
|
|
|
+ Hook->>Hook: Generate available operator options list
|
|
|
|
|
+ Hook->>Hook: Calculate target value's data type Schema
|
|
|
|
|
+ Hook-->>Child: Return {rule, opConfig, opOptionList, targetSchema}
|
|
|
|
|
+ Child-->>App: Render condition component based on returned configurations
|
|
|
|
|
+
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### Dependencies
|
|
|
|
|
+
|
|
|
|
|
+#### flowgram API
|
|
|
|
|
+
|
|
|
|
|
+[**@flowgram.ai/editor**](https://github.com/bytedance/flowgram.ai/tree/main/packages/client/editor)
|
|
|
|
|
+- [`I18n`](https://flowgram.ai/auto-docs/editor/variables/I18n): Internationalization utility class
|
|
|
|
|
+
|
|
|
|
|
+[**@flowgram.ai/json-schema**](https://github.com/bytedance/flowgram.ai/tree/main/packages/common/json-schema)
|
|
|
|
|
+- [`IJsonSchema`](https://flowgram.ai/auto-docs/json-schema/types/IJsonSchema): JSON Schema type definition
|