skt-vuetify-templates/src/components/sections/GUIDE.md

Section Components Guide

src/components/sections 放頁面區塊容器，例如搜尋區、表格、dialog shell、panel。

規則

• 決定布局與區塊互動，不知道 route。
• 檔名使用 Section 前綴。

SectionFormPage

表單申請/填寫頁面通用外殼。最外層為 v-form，內含標題卡片、表單欄位區、子區段插槽、配合事項與動作按鈕列。

使用時機

• 頁面包含送出/存檔按鈕（type="submit"）
• 需要表單驗證與整體 v-form 包覆
• 具有標題卡片、配合事項/注意事項區、動作按鈕列的固定結構
• 例如：申請單、借用單、報名表、維護單等填寫頁面

不適用情境：純粹列表/查詢頁面（無送出按鈕）、結構差異過大的頁面。

視覺特徵

• 頂部標題卡片（bg-primary）
• 中間為表單欄位區（v-text-field/v-select）
• 可能有子區段卡片（明細表格）
• 底部有「配合事項」提示區（bg-yellow-lighten-5）
• 最底部為動作按鈕列（存檔 + 清除 + 返回）

Props

Prop	型別	預設	說明
title	string	—	頁面標題
loading	boolean	undefined	是否顯示 loading
error	string	undefined	錯誤訊息
message	string	undefined	成功訊息
submitLabel	string	'存檔'	送出按鈕文字
resetLabel	string	'清除'	清除按鈕文字
backLabel	string	'返回'	返回按鈕文字

Slots

Slot	用途
#fields	表單欄位區，用 v-row/v-col 配置
#sections	額外子區段卡片（明細、表格等）
#notices	配合事項/注意事項清單

Emits

Emit	說明
@submit	點擊存檔時觸發
@reset	點擊清除時觸發
@back	點擊返回時觸發

範例

<SectionFormPage
  title="設備借用申請"
  :loading="loading"
  :error="error"
  :message="message"
  @submit="save"
  @reset="reset"
  @back="router.push('/venue/apply-choose')"
>
  <template #fields>
    <v-row density="compact">
      <v-col cols="12" md="4">
        <BaseFormTextField v-model="form.cellPhone" label="手機" class="ml-2" />
      </v-col>
    </v-row>
  </template>

  <template #sections>
    <v-card>
      <v-card-title class="text-title-medium font-weight-bold">設備明細</v-card-title>
      <!-- 明細表格 -->
    </v-card>
  </template>

  <template #notices>
    <v-list class="bg-yellow-lighten-5">
      <v-list-item>借用設備時，請愛惜公物。</v-list-item>
    </v-list>
  </template>
</SectionFormPage>

SectionQueryPage

查詢/列表頁面通用外殼。包含標題卡片、篩選條件區、查詢按鈕、結果表格區與返回按鈕。

使用時機

• 頁面具有篩選條件 + 查詢按鈕 + 結果表格的固定結構
• 例如：單筆查詢、列表查詢、報表查詢等頁面

不適用情境：

• 純粹 CRUD 維護頁面（含新增/編輯/刪除操作）→ 用 SectionFormPage
• 頁面結構差異過大（如沒有篩選條件或沒有結果表格）

視覺特徵

• 頂部標題卡片（bg-primary）
• 標題下方為篩選條件區（v-text-field/v-select + 查詢按鈕）
• 下方為結果區：可能是單一表格，也可能是多張獨立卡片表格
• 最底部為返回按鈕
• 與 SectionFormPage 最大差異：沒有「存檔」按鈕，也沒有「配合事項」區

Props

Prop	型別	預設	說明
title	string	—	頁面標題
loading	boolean	undefined	是否顯示 loading
error	string	undefined	錯誤訊息
backLabel	string	'返回'	返回按鈕文字

Slots

Slot	用途
#filters	篩選條件欄位，用 v-col 配置
#results	單一結果表格區（會自動包一層 v-card）
#sections	多區段結果卡片（需自行用 v-card 包覆，適用多表格情境）

#results 與 #sections 擇一使用：

• 單一表格結果 → 用 #results
• 多張獨立表格/列表 → 用 #sections，在 slot 內自行配置 v-card 與標題

Emits

Emit	說明
@search	點擊查詢時觸發
@back	點擊返回時觸發

範例：單一結果表格

<SectionQueryPage
  title="全校設備查詢"
  :loading="loading"
  :error="error"
  @search="search"
  @back="router.push('/venue/query-choose')"
>
  <template #filters>
    <v-col cols="12" md="4">
      <BaseFormSelect v-model="filters.facId" label="設備" :items="facilityItems" />
    </v-col>
    <v-col cols="12" md="4">
      <BaseFormTextField v-model="filters.asOfDate" label="截止日" />
    </v-col>
  </template>

  <template #results>
    <v-table density="compact">
      <thead class="bg-primary">
        <tr>
          <th>設備代碼</th>
          <th>名稱</th>
        </tr>
      </thead>
      <tbody>
        <tr v-if="!result">
          <td class="text-center" colspan="2">尚無查詢結果</td>
        </tr>
        <tr v-else>
          <td>{{ result.facId }}</td>
          <td>{{ result.facName }}</td>
        </tr>
      </tbody>
    </v-table>
  </template>
</SectionQueryPage>

範例：多區段結果（多表格）

<SectionQueryPage
  title="我的申請紀錄"
  :loading="loading"
  :error="error"
  @search="search"
  @back="router.push('/venue/apply-choose')"
>
  <template #filters>
    <v-col cols="12" md="3">
      <BaseFormTextField v-model="filters.startDate" label="查詢起日" />
    </v-col>
    <v-col cols="12" md="3">
      <BaseFormTextField v-model="filters.endDate" label="查詢迄日" />
    </v-col>
    <v-col cols="12" md="3">
      <BaseFormSelect v-model="filters.status" label="狀態" :items="statusItems" />
    </v-col>
  </template>

  <template #sections>
    <v-card>
      <v-card-title class="text-title-medium font-weight-bold py-2">場地申請</v-card-title>
      <v-table density="compact">
        <!-- 場地表格 -->
      </v-table>
    </v-card>

    <v-card>
      <v-card-title class="text-title-medium font-weight-bold py-2">設備申請</v-card-title>
      <v-table density="compact">
        <!-- 設備表格 -->
      </v-table>
    </v-card>
  </template>
</SectionQueryPage>