repository·8.x·Indexed 25 days ago
https://github.com/cool-team-official/cool-admin-vueA modular, plugin-based administrative permission management system built with Vue 3, TypeScript, and Vite. Designed for rapid CRUD development, it features AI-assisted coding, drag-and-drop workflow orchestration, and a comprehensive set of components including cl-crud for data management, cl-dialog for modal interactions, and a programmatic ContextMenu.
The project is built using the following modern web technologies:
After installing the dependencies, you can start the development server by running the following command. Once started, you can preview the application in your browser at http://localhost:9000.
pnpm devTo start working with the project locally, clone the official repository from GitHub.
git clone https://github.com/cool-team-official/cool-admin-vue.gitTo install the necessary dependencies for the cool-admin-vue project, it is recommended to use pnpm.
pnpm iEPS is a mechanism used to synchronize backend API definitions with the frontend. It provides a type-safe way to interact with backend services by automatically generating TypeScript interfaces and service objects based on the actual API structure.
Key Components:
Eps.Entity): Represent backend data models, including their columns, search configurations, and API endpoints./admin/user/info becomes service.user.info)..d.ts or .ts files that provide autocomplete and type checking for API requests, parameters, and responses.config.type. For uniapp-x, it uses export interface and flattens types, whereas for admin or app, it uses declare namespace Eps.The crud object is the central source of truth for a CRUD instance. Its structure includes:
id: The unique identifier (provided via name prop or instance UID).routePath: The current URL path (defaults to location.pathname).loading: Boolean indicating if a data request is in progress.selection: Array of currently selected items.params: Pagination and query parameters (e.g., { page: 1, size: 20 }).service: Configuration for the backend service/API.dict: Dictionary/lookup data.permission: Permission settings merged from global config.mitt: An event emitter instance for component communication.config: Local configuration object.When using cl-select in tree mode, you can control how values are returned using two specific props:
allLevelsId: When enabled, selecting a node will return an array containing the ID of the selected node AND the IDs of all its ancestors. This is useful for maintaining path information in hierarchical data.checkStrictly: When enabled, it decouples the selection state of parent and child nodes. This is passed down to the underlying el-tree-select component.If allLevelsId is false, the component returns only the specific value of the selected node.
The system automatically discovers modules and plugins by scanning specific directory patterns within /src. A module is defined by its location in either src/modules/ or src/plugins/.
To define a module, you can provide the following files/folders:
config.ts: Defines the module's configuration, value, and metadata (like order, enable, or ignore).service/**: Contains service classes. Each service class should have a namespace property which is used as the registration path.directives/**: Contains Vue directives. The filename (without extension) is used as the directive name.Module Metadata Properties:
name: Unique identifier for the module.type: Indicates if it is a 'module' or 'plugin'.value: The core configuration or a function that returns configuration.order: Determines the initialization sequence (higher numbers are processed first).enable: Boolean to toggle the module (defaults to true).install: A function called during bootstrapping: (app: App, options: any) => void.components: An array of components to register (can be a component or a function returning a component).directives: An array of objects containing { name, value } for Vue directive registration.ignore: An array of paths/values to be merged into the global config.ignore list.onLoad: An async lifecycle hook: (events: any) => Promise<any> used to register events.The cl-view-group component is used to create layouts with multiple sections, typically a #left and a #right slot. This is useful for master-detail views, such as showing a list of departments on the left and a list of users on the right.
<cl-view-group>
<template #left>
<!-- Left side content (e.g., a list) -->
</template>
<template #right>
<!-- Right side content (e.g., a CRUD table) -->
</template>
</cl-view-group>Form hooks operate in two modes to manage the data flow between your API and the UI components:
bind mode: Triggered when data is being loaded from the server into the form. The hook transforms the raw API data into a format suitable for form inputs (e.g., converting a JSON string into an object).submit mode: Triggered when the form is being submitted. The hook transforms the form input values back into the format expected by the API (e.g., converting an object into a JSON string).When using complex hooks like splitJoin or json, the logic automatically switches behavior based on the current method.
The cl-form component uses a configuration-driven approach to define fields. Fields are passed via the items property in the open() method.
ClForm.Item)Each item in the items array defines a form field. Key properties include:
prop: The key in the form data object. Supports dot notation (e.g., user.name), which the component automatically converts to a hyphenated key (e.g., user-name) for internal flat state management.type: The type of field (e.g., 'tabs' for tabbed groups).label: The display label for the field.required: Boolean to trigger validation.rules: Validation rules object.children: Nested items for grouping or hierarchical structures.hidden: A boolean or a function (scope) => boolean to determine if the field should be hidden.span: Grid span for the layout (defaulting to style.form.span).hook: A submission hook that runs during the submit() process.When submitting, the component performs invokeData(d). This transforms keys containing hyphens back into nested objects. For example, a key user-name in the flat form state is converted to { user: { name: ... } } in the final submitted object.