forked from mengyxu/noob-components
1 changed files with 254 additions and 0 deletions
@ -0,0 +1,254 @@ |
|||||||
|
# noob-components |
||||||
|
|
||||||
|
## Project Overview |
||||||
|
|
||||||
|
A Vue 3 component library built with TypeScript and Vite, providing reusable UI components and composables for management applications. The library extends Element Plus with custom components, layouts, and utilities. |
||||||
|
|
||||||
|
## Technology Stack |
||||||
|
|
||||||
|
- **Framework**: Vue 3 (Composition API) |
||||||
|
- **Language**: TypeScript |
||||||
|
- **Build Tool**: Vite |
||||||
|
- **Base UI Library**: Element Plus |
||||||
|
- **Styling**: SCSS with scoped styles |
||||||
|
- **State Management**: Vuex (for consuming applications) |
||||||
|
- **Internationalization**: vue3-i18n |
||||||
|
- **Package Manager**: npm/bun |
||||||
|
|
||||||
|
## Project Structure |
||||||
|
|
||||||
|
``` |
||||||
|
noob-components/ |
||||||
|
├── packages/ |
||||||
|
│ ├── base/ # Base UI components |
||||||
|
│ │ ├── data/ # Data display components (ListTable, etc.) |
||||||
|
│ │ ├── item/ # Form input components (Input, Select, DateTime, etc.) |
||||||
|
│ │ └── layout/ # Layout components |
||||||
|
│ ├── manage/ # Management-specific components |
||||||
|
│ │ ├── common/ # Common components (login forms, etc.) |
||||||
|
│ │ └── router/ # Router layout components (index.vue, zhuBeiDong.vue) |
||||||
|
│ └── app.ts # Main export file |
||||||
|
├── plugs/ |
||||||
|
│ ├── composables/ # Vue composables |
||||||
|
│ │ ├── useListTable.ts # Table data management |
||||||
|
│ │ ├── useModifyForm.ts # Form modification logic |
||||||
|
│ │ └── ... |
||||||
|
│ ├── http/ # HTTP utilities and API client |
||||||
|
│ ├── element/ # Element Plus utilities |
||||||
|
│ └── utils/ # General utilities |
||||||
|
├── dist/ # Build output |
||||||
|
│ ├── noob-mengyxu.js |
||||||
|
│ ├── noob-mengyxu.css |
||||||
|
│ └── style.css |
||||||
|
└── vite.config.ts # Vite configuration |
||||||
|
``` |
||||||
|
|
||||||
|
## Key Components |
||||||
|
|
||||||
|
### Router Layouts (`packages/manage/router/`) |
||||||
|
|
||||||
|
Two main layout components for management applications: |
||||||
|
|
||||||
|
- **index.vue**: Standard layout with horizontal/vertical menu support |
||||||
|
- **zhuBeiDong.vue**: Alternative layout with specific styling |
||||||
|
|
||||||
|
Both components: |
||||||
|
- Provide app structure with header, aside, and main content areas |
||||||
|
- Support theme switching (via `state.style`) |
||||||
|
- Support size adjustments (via `state.size`) |
||||||
|
- Handle user authentication checks |
||||||
|
- Use **scoped CSS** with `:deep()` for child component styling |
||||||
|
|
||||||
|
### Login Components (`packages/manage/common/`) |
||||||
|
|
||||||
|
- **login2.vue**: Login form with vertical layout (labels above inputs) |
||||||
|
|
||||||
|
### Data Components (`packages/base/data/`) |
||||||
|
|
||||||
|
- **list-table.vue**: Table component with pagination, sorting, filtering |
||||||
|
- Uses TypeScript interface-based props |
||||||
|
- Integrates with `useListTable` composable |
||||||
|
- Supports Element Plus table features |
||||||
|
|
||||||
|
### Form Components (`packages/base/item/`) |
||||||
|
|
||||||
|
- **input.vue**: Text input wrapper |
||||||
|
- **select.vue**: Select dropdown wrapper |
||||||
|
- **datetime.vue**: Date/time picker wrapper |
||||||
|
- **modify-form.vue**: Form modification component |
||||||
|
|
||||||
|
All form components: |
||||||
|
- Support `.full` class for 100% width |
||||||
|
- Have default constrained width via `.form-item` |
||||||
|
- Use scoped styles |
||||||
|
|
||||||
|
## Key Composables |
||||||
|
|
||||||
|
### useListTable (`plugs/composables/useListTable.ts`) |
||||||
|
|
||||||
|
Manages table data with pagination and filtering. |
||||||
|
|
||||||
|
**Important implementation details:** |
||||||
|
- Uses `deepCopy(toRaw(example))` to avoid infinite reactivity loops |
||||||
|
- Automatically manages pagination params (`page`, `size`) |
||||||
|
- Supports both array and paginated response (`{ data: [], total: N }`) |
||||||
|
- Has `disableAutoQuery` option to disable automatic queries |
||||||
|
|
||||||
|
**Interface:** |
||||||
|
```typescript |
||||||
|
interface TableColumn { |
||||||
|
code: string; // Property path (supports nested like "task.name") |
||||||
|
name?: string; // Display name |
||||||
|
i18n?: string; // i18n key |
||||||
|
type?: string; // Column type |
||||||
|
width?: string | number; |
||||||
|
fixed?: boolean | 'left' | 'right'; |
||||||
|
align?: 'left' | 'center' | 'right'; |
||||||
|
slot?: boolean; // Use custom slot |
||||||
|
dict?: string; // Dictionary for value mapping |
||||||
|
timestamp?: boolean; // Format as timestamp |
||||||
|
filesize?: boolean; // Format as file size |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
### useModifyForm (`plugs/composables/useModifyForm.ts`) |
||||||
|
|
||||||
|
Manages form state for add/edit operations. |
||||||
|
|
||||||
|
## Styling Conventions |
||||||
|
|
||||||
|
### CSS Scoping |
||||||
|
|
||||||
|
- **Router components** (`index.vue`, `zhuBeiDong.vue`): |
||||||
|
- Split into unscoped (for `body`) and scoped blocks |
||||||
|
- Use `:deep()` for child components from library |
||||||
|
- Example: `:deep(.head-icon)`, `:deep(.el-input)` |
||||||
|
|
||||||
|
- **Form components** (`input.vue`, `select.vue`, etc.): |
||||||
|
- Use scoped styles |
||||||
|
- Support `.full` class to override width |
||||||
|
|
||||||
|
### CSS Variables Binding |
||||||
|
|
||||||
|
Components use `v-bind()` to bind Vuex state to CSS: |
||||||
|
```scss |
||||||
|
color: v-bind("state.style.color"); |
||||||
|
background-color: v-bind("state.style.bodyBg"); |
||||||
|
font-size: v-bind("state.size.fontSize"); |
||||||
|
height: v-bind("state.size.headHeight"); |
||||||
|
``` |
||||||
|
|
||||||
|
### State Structure |
||||||
|
|
||||||
|
```typescript |
||||||
|
state.style = { |
||||||
|
color: string; |
||||||
|
bodyBg: string; |
||||||
|
headBg: string; |
||||||
|
itemBg: string; |
||||||
|
selectionBg: string; |
||||||
|
selectionColor: string; |
||||||
|
} |
||||||
|
|
||||||
|
state.size = { |
||||||
|
fontSize: string; |
||||||
|
headHeight: string; |
||||||
|
asideWidth: string; |
||||||
|
mainHeight: string; |
||||||
|
tableHeight: string; |
||||||
|
headIconSize: string; |
||||||
|
size: 'small' | 'default' | 'large'; |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
## Build Configuration |
||||||
|
|
||||||
|
### Library Build (`vite.config.ts`) |
||||||
|
|
||||||
|
- Entry: `packages/app.ts` |
||||||
|
- Output: `dist/noob-mengyxu.js` and `dist/noob-mengyxu.css` |
||||||
|
- CSS is extracted separately (not injected into JS) |
||||||
|
- Vue is externalized (peer dependency) |
||||||
|
|
||||||
|
### Development Workflow |
||||||
|
|
||||||
|
1. **Local development with linking:** |
||||||
|
```bash |
||||||
|
bun link |
||||||
|
cd ../s6a_manage |
||||||
|
bun link noob-mengyxu |
||||||
|
``` |
||||||
|
|
||||||
|
2. **Important**: When using `bun link`, JS/templates load from source but CSS loads from `dist/` |
||||||
|
- After CSS changes, must rebuild: `npm run build:lib` |
||||||
|
|
||||||
|
## Common Issues and Solutions |
||||||
|
|
||||||
|
### Issue: CSS Conflicts from Multiple Router Components |
||||||
|
|
||||||
|
**Problem**: Multiple unscoped CSS rules causing variable conflicts |
||||||
|
|
||||||
|
**Solution**: |
||||||
|
- Use scoped styles with `:deep()` for child elements |
||||||
|
- Split into unscoped (body only) and scoped blocks |
||||||
|
|
||||||
|
### Issue: Infinite Loop in useListTable with deepCopy |
||||||
|
|
||||||
|
**Problem**: `deepCopy(example)` inside `watchEffect` establishes reactive dependencies |
||||||
|
|
||||||
|
**Solution**: Use `deepCopy(toRaw(example))` for deep non-reactive clone |
||||||
|
|
||||||
|
### Issue: Form Input Width Issues |
||||||
|
|
||||||
|
**Problem**: `.form-item` class collision between components |
||||||
|
|
||||||
|
**Solution**: |
||||||
|
- Add `.full { width: 100%; }` to base components |
||||||
|
- Remove conflicting styles from router components |
||||||
|
- Use `:deep()` when needed to style library components |
||||||
|
|
||||||
|
### Issue: Header Icons Not Styled |
||||||
|
|
||||||
|
**Problem**: After scoping, library components don't have scoped attribute |
||||||
|
|
||||||
|
**Solution**: Change `.head-icon` to `:deep(.head-icon)` in router components |
||||||
|
|
||||||
|
## TypeScript Conventions |
||||||
|
|
||||||
|
- Use interface-based prop definitions: `defineProps<Props>()` |
||||||
|
- Use `withDefaults()` for default values |
||||||
|
- Prefer `undefined` over `null` for optional props (simplifies types) |
||||||
|
- Use `() => []` or `() => ({})` for array/object defaults |
||||||
|
|
||||||
|
## Exports |
||||||
|
|
||||||
|
Main export file: `packages/app.ts` |
||||||
|
|
||||||
|
Exports are organized into modules: |
||||||
|
- `Element`: Element Plus utilities |
||||||
|
- `NoobHead`: Header components |
||||||
|
- `NoobInput`, `NoobButton`, etc.: Form components |
||||||
|
- `ListTable`, `ModifyForm`: Data components |
||||||
|
- `Api`: HTTP client |
||||||
|
- `Styles`, `Size`: Theme utilities |
||||||
|
- Composables: `useListTable`, `useModifyForm`, etc. |
||||||
|
|
||||||
|
## Recent Changes |
||||||
|
|
||||||
|
1. **TypeScript Conversion**: Converted list-table.vue to interface-based props |
||||||
|
2. **CSS Scoping**: Fixed conflicts by scoping router component styles |
||||||
|
3. **Reactivity Fix**: Changed to `deepCopy(toRaw(example))` in useListTable |
||||||
|
4. **Form Layout**: Fixed login form to use vertical layout (labels above inputs) |
||||||
|
5. **Pagination**: Fixed handling of paginated responses `{ data: [], total: N }` |
||||||
|
|
||||||
|
## Dependencies |
||||||
|
|
||||||
|
Key dependencies: |
||||||
|
- `vue`: ^3.x |
||||||
|
- `element-plus`: UI library |
||||||
|
- `vue3-i18n`: Internationalization |
||||||
|
- `vuex`: State management (for consumers) |
||||||
|
- `axios`: HTTP client |
||||||
|
- `js-md5`: Password hashing |
||||||
|
- `@vueuse/core`: Vue utilities |
||||||
|
- `lodash-es`: Utility functions |
||||||
Loading…
Reference in new issue