UI Components & Forms
Relevant source files
The following files were used as context for generating this wiki page:
- packages/web/src/components/ControlConfigurationPanel.vue
- packages/web/src/components/ControlConfigurationFields.vue
- packages/web/src/components/SchemaField.vue
- packages/web/src/components/config/RecordListField.vue
- packages/web/src/components/ControlInstallPlanPreview.vue
- packages/web/src/styles/control-configuration.css
- packages/web/src/styles/responsive.css
The UI components and forms system provides the administrative interface for managing the OneBots gateway. It enables users to configure platform accounts, protocol adapters, and runtime settings through a schema-driven form architecture. The system manages a multi-step lifecycle that includes draft editing, server-side validation, and versioned application of configurations.
Configuration Lifecycle and Panel
The ControlConfigurationPanel serves as the primary container for the configuration workflow. It coordinates the transition between local edits and server-side states. The process follows a strict sequence to ensure gateway stability: saving local field changes to a server-side draft, validating the draft for completeness and connection parameters, and explicitly applying the validated version to the running gateway.
The diagram shows the standard progression from draft creation to the application of a new configuration version.
Sources: ControlConfigurationPanel.vue:152-200, ControlConfigurationPanel.vue:220-250
Workspace Management
The configuration interface is divided into four logical workspaces to organize administrative tasks:
- Platform Accounts: Manages identities for various IM platforms (e.g., QQ, WeChat).
- Protocol Egress: Configures how downstream clients connect to the gateway via standards like OneBot or Satori.
- Runtime Settings: Handles service-level parameters and loading arguments.
- Review and Apply: Provides a summary of changes and triggers the final validation and deployment.
Sources: ControlConfigurationPanel.vue:95-120, ControlConfigurationPanel.vue:185-215
Schema-Driven Form Architecture
The form system uses a recursive, schema-driven approach to render UI elements based on backend definitions. The SchemaField component acts as a dispatcher that maps schema types and UI hints to specific input widgets.
Widget Mapping Logic
The system selects widgets based on the type and ui properties of the field definition:
| Schema Type | UI Widget Hint | UI Component |
|---|---|---|
string | N/A | UiInput |
number | N/A | UiNumberInput |
boolean | N/A | UiSwitch |
array | endpoint-list | EndpointListField |
array | record-list | RecordListField |
array | choice-list | ChoiceListField |
object | event-filter | EventFilterField |
Sources: SchemaField.vue:35-55, SchemaField.vue:98-150
Field Tiering and Grouping
Fields are categorized into tiers to improve usability. ControlConfigurationFields separates fields into:
- Primary Fields: Essential settings required for basic functionality.
- Sectioned Fields: Categorized into functional blocks such as Transport, Delivery, Credentials, and Filters.
- Advanced Fields: Less common settings hidden behind a collapsible "More Settings" detail block.
Sources: ControlConfigurationFields.vue:24-35, ControlConfigurationFields.vue:130-160
Complex Data Structures
Record List Management
The RecordListField handles arrays of objects, allowing users to build structured data without writing JSON. It supports:
- Conditional Visibility: Fields within a record appear only when specific sibling values match criteria defined in
visibleWhen. - Dynamic Entry Handling: Users can add or remove entire rows of data while preserving the overall structure.
- Nested Validation: Every sub-field (number, boolean, select, or input) maintains its own data type and sensitivity (e.g., password masking).
Sources: RecordListField.vue:40-75, RecordListField.vue:98-140
Secret State Handling
The configuration system implements a specific state machine for sensitive credentials (secrets). When editing an existing configuration, secrets are managed in three modes:
- Keep: Retains the existing server-side value without revealing it to the browser.
- Set: Provides an input field to overwrite the existing secret.
- Clear: Removes the secret from the configuration.
Sources: ControlConfigurationFields.vue:60-85, ControlConfigurationFields.vue:105-120
Installation and Maintenance UI
The ControlInstallPlanPreview component manages the preview of package updates and removals. It visualizes the impact of changes before the user commits to a gateway modification.
The sequence shows the interaction between the user and the installation preview when handling package dependencies and private tokens.
Sources: ControlInstallPlanPreview.vue:15-60
Styling and Layout
The UI uses a utility-first approach with centralized design tokens for consistency across light and dark modes.
Responsive Design
The system employs a mobile-first responsive strategy defined in responsive.css:
- Desktop Layout: Uses multi-column grids for overview and configuration panels.
- Mobile Layout (≤ 900px): Switches to a single-column layout, hides sidebars, and introduces a dedicated mobile header and navigation bar.
- Touch Optimization: Increases the minimum height of interactive elements (inputs, buttons, select triggers) to
2.75remfor better usability on touch devices.
Sources: responsive.css:1-55, responsive.css:75-105
Configuration Interface Specifics
Specific CSS rules in control-configuration.css manage the density and hierarchy of forms:
- Sticky Action Bars: The "Next Action" bar remains fixed at the bottom of the viewport for easy access to the save/validate flow.
- State Indicators: Uses semantic colors (e.g.,
var(--success)for saved drafts,var(--warning)for local changes) to provide immediate feedback on the configuration status. - Section Spacing: Employs standardized padding (
1.25rem) and border treatments to delineate between different schema groups.
Sources: control-configuration.css:55-75, control-configuration.css:270-300
Conclusion
The OneBots UI component system balances flexibility and safety through its schema-driven architecture. By abstracting complex JSON structures into manageable widgets like RecordListField and implementing a robust lifecycle panel, the system ensures that gateway configurations remain valid and recoverable while providing a responsive, cross-platform experience.