前端開發指引
前端開發指引 文件資訊 版本: 1.0.0 建立日期: 2025-08-11 適用專案: 大型金融級 Web 專案 技術棧: Vue 3.x + TypeScript + Tailwind CSS 目錄 專案目錄與檔案結構規範 命名規範 程式撰寫風格與 Lint 設定 元件開發規範 樣式與 Tailwind CSS 規範 API 串接與資料存取規範 狀態管理規範 多語系處理規範 測試規範 安全性考量 效能優化規範 無障礙設計規範 版本控制與分支策略 專案建置與部署流程 程式碼審查規範 常見錯誤處理與 Debug 流程 開發工具與環境設定 團隊協作與溝通規範 1. 專案目錄與檔案結構規範 1.1 標準專案結構 frontend-project/ ├── public/ # 靜態資源 │ ├── favicon.ico │ ├── index.html │ └── manifest.json ├── src/ # 原始碼 │ ├── api/ # API 相關 │ │ ├── modules/ # 依功能模組分類 │ │ │ ├── auth.ts │ │ │ └── user.ts │ │ ├── interceptors/ # 攔截器 │ │ └── types/ # API 型別定義 │ ├── assets/ # 靜態資源 │ │ ├── images/ │ │ ├── icons/ │ │ └── fonts/ │ ├── components/ # 共用元件 │ │ ├── base/ # 基礎元件 │ │ │ ├── BaseButton.vue │ │ │ ├── BaseInput.vue │ │ │ └── BaseModal.vue │ │ ├── business/ # 業務元件 │ │ └── layout/ # 版面元件 │ │ ├── Header.vue │ │ ├── Sidebar.vue │ │ └── Footer.vue │ ├── composables/ # Vue 3 Composition API │ │ ├── useAuth.ts │ │ ├── useApi.ts │ │ └── useLocalStorage.ts │ ├── constants/ # 常數定義 │ │ ├── api.ts │ │ ├── routes.ts │ │ └── config.ts │ ├── directives/ # 自定義指令 │ ├── i18n/ # 多語系 │ │ ├── locales/ │ │ │ ├── zh-TW.json │ │ │ ├── en-US.json │ │ │ └── ja-JP.json │ │ └── index.ts │ ├── layouts/ # 版面配置 │ │ ├── DefaultLayout.vue │ │ ├── AuthLayout.vue │ │ └── EmptyLayout.vue │ ├── middleware/ # 中間件 │ │ ├── auth.ts │ │ └── permission.ts │ ├── pages/ # 頁面元件 │ │ ├── auth/ │ │ │ ├── Login.vue │ │ │ └── Register.vue │ │ ├── dashboard/ │ │ └── user/ │ ├── plugins/ # 插件 │ │ ├── axios.ts │ │ ├── i18n.ts │ │ └── router.ts │ ├── router/ # 路由設定 │ │ ├── modules/ # 路由模組 │ │ │ ├── auth.ts │ │ │ └── dashboard.ts │ │ └── index.ts │ ├── stores/ # Pinia 狀態管理 │ │ ├── modules/ │ │ │ ├── auth.ts │ │ │ └── user.ts │ │ └── index.ts │ ├── styles/ # 樣式檔案 │ │ ├── globals.css │ │ ├── variables.css │ │ └── components/ │ ├── types/ # TypeScript 型別定義 │ │ ├── api.ts │ │ ├── auth.ts │ │ └── global.ts │ ├── utils/ # 工具函式 │ │ ├── format.ts │ │ ├── validation.ts │ │ └── storage.ts │ ├── App.vue # 根元件 │ └── main.ts # 應用程式進入點 ├── tests/ # 測試檔案 │ ├── unit/ # 單元測試 │ ├── e2e/ # E2E 測試 │ └── __mocks__/ # Mock 檔案 ├── .env # 環境變數 ├── .env.development ├── .env.production ├── .eslintrc.js # ESLint 設定 ├── .prettierrc # Prettier 設定 ├── tailwind.config.js # Tailwind CSS 設定 ├── vite.config.ts # Vite 設定 ├── tsconfig.json # TypeScript 設定 └── package.json # 套件管理 1.2 檔案命名原則 檔案類型對應命名方式 Vue 元件: PascalCase (如 UserProfile.vue) TypeScript 檔案: camelCase (如 userService.ts) CSS/SCSS 檔案: kebab-case (如 user-profile.scss) 測試檔案: 與被測檔案同名 + .test 或 .spec (如 UserProfile.test.ts) 型別定義檔案: camelCase + .d.ts (如 userTypes.d.ts) 特殊檔案命名 頁面元件: PascalCase，通常以頁面功能命名 (如 UserManagement.vue) Layout 元件: PascalCase + Layout 後綴 (如 DashboardLayout.vue) Store 檔案: camelCase，以業務領域命名 (如 userStore.ts) API 檔案: camelCase，以 API 服務命名 (如 userApi.ts) 2. 命名規範 2.1 檔案與資料夾命名 資料夾命名 使用 kebab-case (小寫字母 + 連字號) 名稱應簡潔且具描述性 ✅ 正確範例 user-management/ auth-service/ api-client/ ❌ 錯誤範例 UserManagement/ authService/ API_Client/ 檔案命名 Vue 元件檔案: PascalCase JavaScript/TypeScript 檔案: camelCase 樣式檔案: kebab-case 設定檔案: kebab-case 或 camelCase (依慣例) // ✅ 正確範例 UserProfile.vue userService.ts user-profile.scss vite.config.ts // ❌ 錯誤範例 userprofile.vue UserService.ts user_profile.scss vite_config.ts 2.2 變數與函式命名 JavaScript/TypeScript 變數 使用 camelCase 常數使用 UPPER_SNAKE_CASE 私有變數以 _ 開頭 布林值變數使用 is、has、can、should 等前綴 // ✅ 正確範例 const userName = 'John Doe'; const API_BASE_URL = 'https://api.example.com'; const _privateVariable = 'private'; const isLoggedIn = true; const hasPermission = false; const canEdit = true; const shouldUpdate = false; // ❌ 錯誤範例 const user_name = 'John Doe'; const apiBaseUrl = 'https://api.example.com'; // 常數應使用大寫 const privateVariable = 'private'; // 私有變數缺少前綴 const loggedIn = true; // 布林值缺少前綴 函式命名 使用 camelCase 動詞開頭，描述函式的動作 事件處理器使用 handle 前綴 取得資料使用 get、fetch 前綴 設定資料使用 set、update 前綴 // ✅ 正確範例 function getUserData() { } function handleButtonClick() { } function validateEmail() { } function formatCurrency() { } function updateUserProfile() { } function fetchUserList() { } // ❌ 錯誤範例 function userData() { } // 缺少動詞 function buttonClick() { } // 事件處理器缺少 handle 前綴 function email() { } // 不明確的命名 function currency() { } // 不明確的命名 2.3 Vue 元件命名 元件名稱 使用 PascalCase 多個單字組合，避免單一單字 基礎元件使用 Base 前綴 業務元件使用具體的業務領域命名 <!-- ✅ 正確範例 --> <script setup lang="ts"> // 元件檔案: UserProfile.vue </script> <script setup lang="ts"> // 元件檔案: BaseButton.vue </script> <script setup lang="ts"> // 元件檔案: PaymentForm.vue </script> <!-- ❌ 錯誤範例 --> <script setup lang="ts"> // 元件檔案: user.vue - 命名太簡短 </script> <script setup lang="ts"> // 元件檔案: button.vue - 應使用 BaseButton </script> Props 命名 定義時使用 camelCase HTML 模板中使用 kebab-case <script setup lang="ts"> // ✅ 正確範例 interface Props { userName: string; isVisible: boolean; maxLength?: number; } const props = withDefaults(defineProps<Props>(), { maxLength: 100 }); </script> <template> <!-- HTML 模板中使用 kebab-case --> <UserProfile :user-name="currentUser" :is-visible="showProfile" :max-length="200" /> </template> Event 命名 使用 kebab-case 動詞開頭，描述事件的動作 <script setup lang="ts"> // ✅ 正確範例 const emit = defineEmits<{ 'update:modelValue': [value: string]; 'user-created': [user: User]; 'form-submitted': [data: FormData]; 'item-selected': [item: Item]; }>(); // 觸發事件 emit('user-created', newUser); emit('form-submitted', formData); </script> 3. 程式撰寫風格與 Lint 設定 3.1 ESLint 設定 eslint.config.js 範例 import { defineConfig } from 'eslint-define-config'; import vue from 'eslint-plugin-vue'; import typescript from '@typescript-eslint/eslint-plugin'; import typescriptParser from '@typescript-eslint/parser'; import prettier from 'eslint-plugin-prettier'; export default defineConfig([ { files: ['**/*.{js,ts,vue}'], languageOptions: { parser: typescriptParser, parserOptions: { ecmaVersion: 2022, sourceType: 'module', extraFileExtensions: ['.vue'] } }, plugins: { vue, '@typescript-eslint': typescript, prettier }, rules: { // Vue 規則 'vue/multi-word-component-names': 'error', 'vue/component-name-in-template-casing': ['error', 'PascalCase'], 'vue/no-unused-vars': 'error', 'vue/no-multiple-template-root': 'off', // Vue 3 支援多個根元素 'vue/script-setup-uses-vars': 'error', // TypeScript 規則 '@typescript-eslint/no-unused-vars': 'error', '@typescript-eslint/no-explicit-any': 'warn', '@typescript-eslint/explicit-function-return-type': 'off', '@typescript-eslint/no-non-null-assertion': 'warn', // 通用規則 'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn', 'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'warn', 'prefer-const': 'error', 'no-var': 'error', 'object-shorthand': 'error', 'prefer-template': 'error', // Prettier 規則 'prettier/prettier': 'error' } } ]); 3.2 Prettier 設定 .prettierrc 範例 { "semi": true, "trailingComma": "es5", "singleQuote": true, "printWidth": 80, "tabWidth": 2, "useTabs": false, "bracketSpacing": true, "bracketSameLine": false, "arrowParens": "avoid", "endOfLine": "lf", "vueIndentScriptAndStyle": true, "htmlWhitespaceSensitivity": "css" } 3.3 TypeScript 撰寫規範 型別定義規範 // ✅ 正確範例 - 使用 interface 定義物件型別 interface User { id: number; name: string; email: string; isActive: boolean; createdAt: Date; updatedAt?: Date; // 選擇性屬性 } // ✅ 正確範例 - 使用 type 定義聯合型別 type Status = 'pending' | 'approved' | 'rejected'; type Theme = 'light' | 'dark' | 'auto'; // ✅ 正確範例 - 泛型使用 interface ApiResponse<T> { data: T; message: string; success: boolean; code: number; } // ✅ 正確範例 - 函式型別定義 type EventHandler<T = Event> = (event: T) => void; type AsyncFunction<T> = () => Promise<T>; 函式撰寫規範 // ✅ 正確範例 - 明確的參數和回傳型別 async function fetchUserData(userId: number): Promise<User | null> { try { const response = await api.get<ApiResponse<User>>(`/users/${userId}`); return response.data.data; } catch (error) { console.error('Failed to fetch user data:', error); return null; } } // ✅ 正確範例 - 箭頭函式與型別推斷 const formatCurrency = (amount: number, currency = 'TWD'): string => { return new Intl.NumberFormat('zh-TW', { style: 'currency', currency, }).format(amount); }; // ✅ 正確範例 - 高階函式 const createValidator = <T>( validator: (value: T) => boolean, errorMessage: string ) => { return (value: T): ValidationResult => ({ isValid: validator(value), message: validator(value) ? '' : errorMessage, }); }; 3.4 Vue 3 Composition API 撰寫規範 <script setup> 結構規範 <script setup lang="ts"> // 1. 導入 Vue 相關 API import { ref, computed, watch, onMounted } from 'vue'; // 2. 導入 Composables import { useAuth } from '@/composables/useAuth'; import { useApi } from '@/composables/useApi'; // 3. 導入其他模組 import { formatDate } from '@/utils/format'; import type { User } from '@/types/user'; // 4. 定義 Props 介面 interface Props { userId: number; isEditable?: boolean; } // 5. 定義 Emits 介面 interface Emits { 'user-updated': [user: User]; 'error': [error: string]; } // 6. 宣告 Props 和 Emits const props = withDefaults(defineProps<Props>(), { isEditable: false, }); const emit = defineEmits<Emits>(); // 7. 響應式資料 const user = ref<User | null>(null); const loading = ref(false); const error = ref<string>(''); // 8. 計算屬性 const displayName = computed(() => { return user.value ? `${user.value.firstName} ${user.value.lastName}` : ''; }); const canEdit = computed(() => { return props.isEditable && user.value?.isActive; }); // 9. 監聽器 watch( () => props.userId, async (newUserId) => { if (newUserId) { await loadUser(); } }, { immediate: true } ); // 10. 方法 const loadUser = async (): Promise<void> => { loading.value = true; error.value = ''; try { const userData = await fetchUserData(props.userId); user.value = userData; } catch (err) { error.value = '載入使用者資料失敗'; emit('error', error.value); } finally { loading.value = false; } }; const updateUser = async (userData: Partial<User>): Promise<void> => { if (!user.value) return; try { const updatedUser = await updateUserData(user.value.id, userData); user.value = updatedUser; emit('user-updated', updatedUser); } catch (err) { error.value = '更新使用者資料失敗'; emit('error', error.value); } }; // 11. 生命週期鉤子 onMounted(() => { console.log('Component mounted'); }); // 12. 暴露給父元件的方法/屬性 (如需要) defineExpose({ loadUser, updateUser, }); </script> 3.5 程式碼品質規範 註解撰寫規範 /** * 使用者資料服務類別 * * 提供使用者相關的 API 操作方法，包含： * - 取得使用者資料 * - 更新使用者資料 * - 刪除使用者 * * @example * ```typescript * const userService = new UserService(); * const user = await userService.getUser(123); * ``` */ export class UserService { /** * 根據 ID 取得使用者資料 * * @param userId - 使用者 ID * @returns 使用者資料，如果找不到則回傳 null * @throws {ApiError} 當 API 請求失敗時拋出錯誤 * * @example * ```typescript * const user = await userService.getUser(123); * if (user) { * console.log(user.name); * } * ``` */ async getUser(userId: number): Promise<User | null> { // TODO: 實作快取機制 // FIXME: 處理網路錯誤重試邏輯 try { const response = await this.api.get(`/users/${userId}`); return response.data; } catch (error) { // 記錄錯誤但不拋出，讓呼叫方決定如何處理 console.error(`Failed to fetch user ${userId}:`, error); return null; } } } 錯誤處理規範 // ✅ 正確範例 - 統一的錯誤處理 export class ApiError extends Error { constructor( message: string, public status: number, public code?: string ) { super(message); this.name = 'ApiError'; } } // ✅ 正確範例 - 錯誤邊界處理 const handleApiError = (error: unknown): never => { if (error instanceof ApiError) { switch (error.status) { case 401: // 重新導向到登入頁面 router.push('/login'); break; case 403: // 顯示權限不足訊息 showErrorMessage('您沒有權限執行此操作'); break; case 500: // 顯示伺服器錯誤訊息 showErrorMessage('伺服器發生錯誤，請稍後再試'); break; default: showErrorMessage(error.message); } } else { // 未知錯誤 console.error('Unexpected error:', error); showErrorMessage('發生未知錯誤'); } throw error; }; 4. 元件開發規範 4.1 Vue 單檔元件 (SFC) 結構 標準 SFC 結構順序 <!-- 1. 模板區域 --> <template> <div class="user-profile"> <!-- 內容 --> </div> </template> <!-- 2. 邏輯區域 --> <script setup lang="ts"> // 邏輯代碼 </script> <!-- 3. 樣式區域 --> <style scoped lang="scss"> // 樣式代碼 </style> 完整元件範例 <template> <div class="user-card" :class="cardClasses"> <!-- 頭像區域 --> <div class="user-card__avatar"> <img :src="user.avatar || defaultAvatar" :alt="`${user.name} 的頭像`" class="user-card__avatar-img" @error="handleImageError" /> <div v-if="showStatus" class="user-card__status" :class="statusClass"> {{ statusText }} </div> </div> <!-- 使用者資訊 --> <div class="user-card__content"> <h3 class="user-card__name">{{ user.name }}</h3> <p class="user-card__email">{{ user.email }}</p> <!-- 標籤 --> <div v-if="user.tags?.length" class="user-card__tags"> <span v-for="tag in user.tags" :key="tag" class="user-card__tag" > {{ tag }} </span> </div> <!-- 動作按鈕 --> <div class="user-card__actions"> <BaseButton variant="primary" size="small" :disabled="loading" @click="handleEdit" > 編輯 </BaseButton> <BaseButton variant="secondary" size="small" :disabled="loading" @click="handleView" > 查看 </BaseButton> </div> </div> <!-- 載入狀態 --> <div v-if="loading" class="user-card__loading"> <LoadingSpinner size="small" /> </div> </div> </template> <script setup lang="ts"> import { computed, ref } from 'vue'; import BaseButton from '@/components/base/BaseButton.vue'; import LoadingSpinner from '@/components/base/LoadingSpinner.vue'; import { useI18n } from 'vue-i18n'; import type { User } from '@/types/user'; // Props 定義 interface Props { user: User; variant?: 'default' | 'compact' | 'detailed'; showStatus?: boolean; interactive?: boolean; } // Emits 定義 interface Emits { edit: [user: User]; view: [user: User]; 'avatar-error': [user: User]; } const props = withDefaults(defineProps<Props>(), { variant: 'default', showStatus: true, interactive: true, }); const emit = defineEmits<Emits>(); // Composables const { t } = useI18n(); // 響應式資料 const loading = ref(false); const defaultAvatar = '/images/default-avatar.png'; // 計算屬性 const cardClasses = computed(() => ({ [`user-card--${props.variant}`]: true, 'user-card--interactive': props.interactive, 'user-card--loading': loading.value, })); const statusClass = computed(() => ({ 'user-card__status--online': props.user.isOnline, 'user-card__status--offline': !props.user.isOnline, })); const statusText = computed(() => { return props.user.isOnline ? t('common.online') : t('common.offline'); }); // 方法 const handleEdit = (): void => { if (!props.interactive || loading.value) return; emit('edit', props.user); }; const handleView = (): void => { if (!props.interactive || loading.value) return; emit('view', props.user); }; const handleImageError = (): void => { emit('avatar-error', props.user); }; </script> <style scoped lang="scss"> .user-card { @apply bg-white rounded-lg shadow-md p-4 transition-all duration-200; &--interactive { @apply hover:shadow-lg cursor-pointer; } &--loading { @apply opacity-50 pointer-events-none; } &__avatar { @apply relative flex-shrink-0; } &__avatar-img { @apply w-12 h-12 rounded-full object-cover; } &__status { @apply absolute -bottom-1 -right-1 px-2 py-1 text-xs rounded-full text-white; &--online { @apply bg-green-500; } &--offline { @apply bg-gray-400; } } &__content { @apply flex-1 ml-4; } &__name { @apply text-lg font-semibold text-gray-900 mb-1; } &__email { @apply text-sm text-gray-600 mb-2; } &__tags { @apply flex flex-wrap gap-1 mb-3; } &__tag { @apply px-2 py-1 text-xs bg-blue-100 text-blue-800 rounded; } &__actions { @apply flex gap-2; } &__loading { @apply absolute inset-0 flex items-center justify-center bg-white bg-opacity-75; } // 變體樣式 &--compact { @apply p-2; .user-card__avatar-img { @apply w-8 h-8; } .user-card__name { @apply text-base; } } &--detailed { @apply p-6; .user-card__avatar-img { @apply w-16 h-16; } } } </style> 4.2 Props 設計規範 Props 型別定義 // ✅ 正確範例 - 完整的 Props 介面 interface ButtonProps { // 必要屬性 label: string; // 選擇性屬性with default values variant?: 'primary' | 'secondary' | 'danger' | 'ghost'; size?: 'small' | 'medium' | 'large'; disabled?: boolean; loading?: boolean; // 複雜型別 icon?: { name: string; position: 'left' | 'right'; }; // 函式型別 onClick?: (event: MouseEvent) => void; } const props = withDefaults(defineProps<ButtonProps>(), { variant: 'primary', size: 'medium', disabled: false, loading: false, }); Props 驗證 // ✅ 正確範例 - 執行時驗證 interface FormInputProps { modelValue: string; type?: 'text' | 'email' | 'password' | 'number'; placeholder?: string; required?: boolean; maxLength?: number; pattern?: string; validator?: (value: string) => boolean | string; } const props = withDefaults(defineProps<FormInputProps>(), { type: 'text', required: false, }); // 自定義驗證邏輯 const isValid = computed(() => { if (props.required && !props.modelValue) { return false; } if (props.maxLength && props.modelValue.length > props.maxLength) { return false; } if (props.pattern && !new RegExp(props.pattern).test(props.modelValue)) { return false; } if (props.validator) { const result = props.validator(props.modelValue); return result === true; } return true; }); 4.3 Emits 事件規範 事件定義與觸發 // ✅ 正確範例 - 型別安全的事件定義 interface FormEmits { // v-model 雙向綁定 'update:modelValue': [value: string]; // 表單事件 submit: [data: FormData]; cancel: []; // 驗證事件 'validation-error': [errors: ValidationError[]]; 'validation-success': []; // 使用者互動事件 'field-focus': [fieldName: string]; 'field-blur': [fieldName: string, value: string]; } const emit = defineEmits<FormEmits>(); // 事件觸發範例 const handleSubmit = (formData: FormData): void => { // 驗證表單 const errors = validateForm(formData); if (errors.length > 0) { emit('validation-error', errors); return; } emit('validation-success'); emit('submit', formData); }; const handleCancel = (): void => { emit('cancel'); }; // v-model 實作 const updateValue = (newValue: string): void => { emit('update:modelValue', newValue); }; 4.4 Slots 使用規範 具名插槽設計 <template> <div class="card"> <!-- 標題插槽 --> <header v-if="$slots.header" class="card__header"> <slot name="header" :title="title" :subtitle="subtitle" /> </header> <!-- 預設內容插槽 --> <main class="card__content"> <slot :data="data" :loading="loading" /> </main> <!-- 動作按鈕插槽 --> <footer v-if="$slots.actions" class="card__actions"> <slot name="actions" :save="handleSave" :cancel="handleCancel" :canSave="canSave" /> </footer> <!-- 條件式插槽 --> <div v-if="$slots.sidebar" class="card__sidebar"> <slot name="sidebar" /> </div> </div> </template> <script setup lang="ts"> interface Props { title?: string; subtitle?: string; data: any; loading?: boolean; } const props = defineProps<Props>(); // 計算屬性 const canSave = computed(() => { return !props.loading && isDataValid(props.data); }); // 提供給插槽的方法 const handleSave = (): void => { // 儲存邏輯 }; const handleCancel = (): void => { // 取消邏輯 }; </script> 插槽使用範例 <template> <Card :data="userData" :loading="loading"> <!-- 標題插槽 --> <template #header="{ title, subtitle }"> <h2>{{ title || '使用者資料' }}</h2> <p v-if="subtitle">{{ subtitle }}</p> </template> <!-- 預設內容插槽 --> <template #default="{ data, loading }"> <div v-if="!loading"> <UserForm :user="data" @update="handleUserUpdate" /> </div> <LoadingSpinner v-else /> </template> <!-- 動作插槽 --> <template #actions="{ save, cancel, canSave }"> <BaseButton variant="primary" :disabled="!canSave" @click="save" > 儲存 </BaseButton> <BaseButton variant="secondary" @click="cancel" > 取消 </BaseButton> </template> </Card> </template> 4.5 元件組合與複用 高階元件 (HOC) 模式 <!-- withLoading.vue - 高階元件 --> <template> <div class="with-loading"> <div v-if="loading" class="loading-overlay"> <LoadingSpinner :size="loadingSize" /> <p v-if="loadingText">{{ loadingText }}</p> </div> <div :class="{ 'is-loading': loading }"> <slot :loading="loading" /> </div> </div> </template> <script setup lang="ts"> interface Props { loading: boolean; loadingText?: string; loadingSize?: 'small' | 'medium' | 'large'; } withDefaults(defineProps<Props>(), { loadingSize: 'medium', }); </script> 組合式元件使用 <template> <WithLoading :loading="isLoading" loading-text="載入使用者資料中..."> <UserProfile :user="userData" @edit="handleEdit" @delete="handleDelete" /> </WithLoading> </template> <script setup lang="ts"> import WithLoading from '@/components/hoc/WithLoading.vue'; import UserProfile from '@/components/UserProfile.vue'; const isLoading = ref(false); const userData = ref(null); const handleEdit = (user: User): void => { // 編輯邏輯 }; const handleDelete = (user: User): void => { // 刪除邏輯 }; </script> 5. 樣式與 Tailwind CSS 規範 5.1 Tailwind CSS 設定 tailwind.config.js 範例 /** @type {import('tailwindcss').Config} */ export default { content: [ './index.html', './src/**/*.{vue,js,ts,jsx,tsx}', ], theme: { extend: { // 顏色系統 colors: { primary: { 50: '#eff6ff', 100: '#dbeafe', 200: '#bfdbfe', 300: '#93c5fd', 400: '#60a5fa', 500: '#3b82f6', // 主要品牌色 600: '#2563eb', 700: '#1d4ed8', 800: '#1e40af', 900: '#1e3a8a', 950: '#172554', }, secondary: { 50: '#f8fafc', 500: '#64748b', 900: '#0f172a', }, success: { 50: '#f0fdf4', 500: '#22c55e', 900: '#14532d', }, warning: { 50: '#fffbeb', 500: '#f59e0b', 900: '#78350f', }, danger: { 50: '#fef2f2', 500: '#ef4444', 900: '#7f1d1d', }, }, // 字型設定 fontFamily: { sans: [ 'Noto Sans TC', 'Microsoft JhengHei', 'PingFang TC', 'Helvetica Neue', 'Arial', 'sans-serif', ], }, // 響應式斷點 screens: { 'xs': '475px', 'sm': '640px', 'md': '768px', 'lg': '1024px', 'xl': '1280px', '2xl': '1536px', }, }, }, plugins: [ require('@tailwindcss/forms'), require('@tailwindcss/typography'), ], }; 5.2 RWD 響應式設計原則 Mobile-First 設計策略 <template> <!-- 響應式網格系統 --> <div class="container mx-auto px-4"> <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4"> <div v-for="item in items" :key="item.id" class="card"> <!-- 響應式圖片 --> <img :src="item.image" :alt="item.title" class="w-full h-32 sm:h-40 lg:h-48 object-cover" /> <!-- 響應式文字 --> <div class="p-4"> <h3 class="text-lg sm:text-xl lg:text-2xl font-semibold"> {{ item.title }} </h3> <p class="text-sm sm:text-base text-gray-600"> {{ item.description }} </p> </div> </div> </div> </div> <!-- 響應式導航 --> <nav class="bg-white shadow"> <!-- 桌面版導航 --> <div class="hidden lg:flex items-center space-x-8 px-6 py-4"> <a v-for="link in navLinks" :key="link.path" :href="link.path"> {{ link.title }} </a> </div> <!-- 行動版選單 --> <div class="lg:hidden"> <button @click="toggleMobileMenu" class="p-4"> <MenuIcon class="w-6 h-6" /> </button> </div> </nav> </template> 5.3 顏色與主題設計 CSS 變數主題系統 :root { /* 品牌色 */ --color-primary: #3b82f6; --color-secondary: #64748b; /* 語意化顏色 */ --color-success: #22c55e; --color-warning: #f59e0b; --color-danger: #ef4444; /* 背景色 */ --bg-primary: #ffffff; --bg-secondary: #f8fafc; /* 文字色 */ --text-primary: #111827; --text-secondary: #4b5563; } /* 暗色主題 */ [data-theme="dark"] { --bg-primary: #111827; --bg-secondary: #1f2937; --text-primary: #f9fafb; --text-secondary: #d1d5db; } 5.4 共用樣式元件 基礎元件樣式 @layer components { /* 按鈕樣式 */ .btn { @apply inline-flex items-center px-4 py-2 text-sm font-medium rounded-md transition-colors focus:outline-none focus:ring-2; } .btn-primary { @apply btn bg-primary-500 text-white hover:bg-primary-600; } .btn-secondary { @apply btn bg-gray-200 text-gray-900 hover:bg-gray-300; } /* 表單樣式 */ .form-input { @apply w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-1 focus:ring-primary-500 focus:border-primary-500; } /* 卡片樣式 */ .card { @apply bg-white rounded-lg shadow-md p-4; } } 總結 本前端開發指引提供了完整的開發規範，涵蓋了專案結構、命名規範、程式撰寫風格、元件開發和樣式設計等核心面向。請開發團隊嚴格遵循這些規範，以確保程式碼品質和專案的可維護性。 ...