# 表格组件使用说明

> 基于 `page-table` + `page-dialog-form` 的新一�?CRUD 表格方案�? 
> 源码位置：`src/components/page-table/`、`src/components/page-dialog-form/`、`src/composables/`  
> 完整可运行示例：`src/views/production-master-data/factory-model/factory-area/index.vue`

---

## 目录

1. [快速开始（三步走）](#1-快速开始三步走)
2. [完整示例代码](#2-完整示例代码)
3. [组件 API 参考](#3-组件-api-参�?
4. [Composable API 参考](#4-composable-api-参�?
5. [i18n 国际化方案](#5-i18n-国际化方�?
6. [常用场景速查](#6-常用场景速查)
7. [路由配置](#7-路由配置)
8. [API 文件写法](#8-api-文件写法)
9. [旧代码迁移对照](#9-旧代码迁移对�?
10. [常见问题排查](#10-常见问题排查)

---

## 1. 快速开始（三步走）

### 第一步：定义列和按钮（`created()` 中）

```js
import { useTableColumns } from '@/composables/useTableColumns'
import { useTableButtons } from '@/composables/useTableButtons'
import { i18nMixin } from '@/composables/useI18n'

export default {
  mixins: [i18nMixin('page.模块�?二级模块.三级模块')],

  created () {
    // --- 列定�?---
    // 只需声明 prop �?label，idx 自动补齐
    // prop: '_actions' 约定为操作列，自动渲�?rowButtons
    this.columns = useTableColumns([
      { prop: 'sort', label: this.key('sort'), width: 80 },
      { prop: 'code', label: this.key('code'), minWidth: 120 },
      { prop: 'name', label: this.key('name') },
      { prop: '_actions', label: this.key('operation'), width: 160, fixed: 'right' }
    ])

    // --- 按钮定义 ---
    // 不再分开�?buttonList / tableButtonList
    const btns = useTableButtons({
      toolbar: [
        { key: 'add', label: this.key('add'), icon: 'el-icon-plus',
          type: 'primary', auth: '/xxx/create', onClick: this.openAdd }
      ],
      row: [
        { key: 'edit', label: this.key('edit'), icon: 'el-icon-edit',
          auth: '/xxx/edit', onClick: this.openEdit },
        { key: 'delete', label: this.key('delete'), icon: 'el-icon-delete',
          color: 'danger', auth: '/xxx/delete', onClick: this.handleDelete }
      ]
    }, this.$permission) // �?第二个参数传入权限校验函�?
    this.toolbarButtons = btns.toolbarButtons
    this.rowButtons = btns.rowButtons
  }
}
```

### 第二步：写模板（`<template>` 中）

```vue
<template>
  <d2-container>
    <!-- 搜索�?-->
    <template #header>
      <el-form :inline="true" size="mini">
        <el-form-item :label="$t(key('code'))">
          <el-input v-model="search.code" :placeholder="$t(key('enter_code'))"
                    clearable style="width:200px" @keyup.enter.native="onSearch" />
        </el-form-item>
        <el-form-item>
          <el-button type="primary" icon="el-icon-search" @click="onSearch">
            {{ $t(key('search')) }}
          </el-button>
          <el-button icon="el-icon-refresh" @click="onReset">
            {{ $t(key('reset')) }}
          </el-button>
        </el-form-item>
      </el-form>
    </template>

    <!-- 表格 + 按钮�?+ 分页 -->
    <page-table
      :columns="columns"
      :data="tableData"
      :loading="loading"
      :toolbar-buttons="toolbarButtons"
      :row-buttons="rowButtons"
      :pagination="pagination"
      help-url="/help/your-page"
      auto-height
      @page-change="onPageChange"
      @selection-change="onSelect"
    />

    <!-- 新增/编辑弹框 -->
    <page-dialog-form
      ref="dialogForm"
      :visible.sync="dialogVisible"
      :title="dialogTitle"
      width="35%"
      :form-cols="formCols"
      :form-data="formData"
      :rules="rules"
      :submitting="submitting"
      :confirm-text="$t(key('confirm'))"
      :cancel-text="$t(key('cancel'))"
      @submit="onDialogSubmit"
      @close="onDialogClose"
    />
  </d2-container>
</template>
```

### 第三步：写业务方法（增删改查�?
```js
methods: {
  // 获取列表数据
  async fetchData () {
    this.loading = true
    try {
      const res = await getList({
        ...this.search,
        page_no: this.pagination.current,
        page_size: this.pagination.size
      })
      this.tableData = res.data || []
      this.pagination.total = res.count || 0
    } finally { this.loading = false }
  },

  // 搜索 / 重置
  onSearch () { this.pagination.current = 1; this.fetchData() },
  onReset () { this.search = { code: '', name: '' }; this.pagination.current = 1; this.fetchData() },

  // 分页变化
  onPageChange (page) {
    this.pagination.current = page.current
    this.pagination.size = page.size
    this.fetchData()
  },

  // 新增：打开弹窗
  openAdd () {
    this.handleType = 'create'
    this.dialogTitle = this.key('add_title')
    this.$nextTick(() => {
      this.$refs.dialogForm.reset()
      this.resetForm()
      this.dialogVisible = true
    })
  },

  // 编辑：回填表�?  openEdit (row) {
    this.handleType = 'edit'
    this.dialogTitle = this.key('edit_title')
    this.editId = row.id
    this.formData = { code: row.code, name: row.name }
    this.dialogVisible = true
  },

  // 提交表单
  async onDialogSubmit () {
    this.submitting = true
    try {
      if (this.handleType === 'create') {
        await createApi(this.formData)
      } else {
        await editApi({ ...this.formData, id: this.editId })
      }
      this.$message.success(this.$t(this.key('operation_success')))
      this.dialogVisible = false
      this.fetchData()
    } finally { this.submitting = false }
  },

  // 关闭弹窗
  onDialogClose () { this.resetForm() },

  // 删除
  async handleDelete (row) {
    try {
      await this.$confirm(
        this.$t(this.key('confirm_delete')),
        this.$t(this.key('tip')),
        { confirmButtonText: this.$t(this.key('confirm')),
          cancelButtonText: this.$t(this.key('cancel')),
          type: 'warning', closeOnClickModal: false }
      )
      await deleteApi({ id: [row.id] })
      this.$message.success(this.$t(this.key('operation_success')))
      this.fetchData()
    } catch (e) { /* 取消或失�?*/ }
  }
}
```

---

## 2. 完整示例代码

> 📁 `src/views/production-master-data/factory-model/factory-area/index.vue`  
> 这是一�?*可直接运行的完整 CRUD 页面**，包含搜索栏、表格、分页、新�?编辑弹框、删除确认�?
### 模板部分

```vue
<template>
  <d2-container>
    <template #header>
      <div class="search-bar">
        <el-form :inline="true" size="mini">
          <el-form-item :label="$t(key('code'))">
            <el-input v-model="search.code" :placeholder="$t(key('enter_code'))"
                      clearable style="width:200px" @keyup.enter.native="onSearch" />
          </el-form-item>
          <el-form-item :label="$t(key('name'))">
            <el-input v-model="search.name" :placeholder="$t(key('enter_name'))"
                      clearable style="width:200px" @keyup.enter.native="onSearch" />
          </el-form-item>
          <el-form-item>
            <el-button type="primary" icon="el-icon-search" @click="onSearch">
              {{ $t(key('search')) }}
            </el-button>
            <el-button icon="el-icon-refresh" @click="onReset">
              {{ $t(key('reset')) }}
            </el-button>
          </el-form-item>
        </el-form>
      </div>
    </template>

    <page-table
      ref="pageTable"
      :columns="columns"
      :data="tableData"
      :loading="loading"
      :toolbar-buttons="toolbarButtons"
      :row-buttons="rowButtons"
      :pagination="pagination"
      help-url="/help/factory-area"
      auto-height
      @page-change="onPageChange"
      @selection-change="onSelect"
    />

    <page-dialog-form
      ref="dialogForm"
      :visible.sync="dialogVisible"
      :title="dialogTitle"
      width="35%"
      :form-cols="formCols"
      :form-data="formData"
      :rules="rules"
      :submitting="submitting"
      :confirm-text="$t(key('confirm'))"
      :cancel-text="$t(key('cancel'))"
      @submit="onDialogSubmit"
      @close="onDialogClose"
    />
  </d2-container>
</template>
```

### Script 部分

```js
import { useTableColumns } from '@/composables/useTableColumns'
import { useTableButtons } from '@/composables/useTableButtons'
import { i18nMixin } from '@/composables/useI18n'
import { getFactoryAreaList, createFactoryArea, editFactoryArea, deleteFactoryArea }
  from '@/api/production-master-data/factory-area'
import PageTable from '@/components/page-table'
import PageDialogForm from '@/components/page-dialog-form'

export default {
  name: 'factory-area',
  components: { PageTable, PageDialogForm },
  mixins: [i18nMixin('page.production_master_data.factory_model.factory_area')],

  data () {
    const t = this.$t.bind(this)
    const k = (s) => t(this.key(s))
    return {
      loading: false,
      submitting: false,
      tableData: [],
      selectedRows: [],
      dialogVisible: false,
      dialogTitle: '',
      editId: '',
      handleType: 'create',
      search: { code: '', name: '' },
      pagination: { current: 1, size: 10, total: 0 },
      formData: { code: '', name: '', remark: '' },
      rules: {
        code: [
          { required: true, message: k('enter_code'), trigger: 'blur' },
          { min: 1, max: 100, message: k('remark_length'), trigger: 'blur' }
        ],
        name: [
          { required: true, message: k('enter_name'), trigger: 'blur' },
          { min: 1, max: 100, message: k('remark_length'), trigger: 'blur' }
        ]
      },
      columns: [],
      toolbarButtons: [],
      rowButtons: [],
      formCols: [
        [
          { type: 'input', prop: 'code',
            label: k('code'), placeholder: k('enter_code'),
            clearable: true, style: { width: '90%' } }
        ],
        [
          { type: 'input', prop: 'name',
            label: k('name'), placeholder: k('enter_name'),
            clearable: true, style: { width: '90%' } }
        ],
        [
          { type: 'input', prop: 'remark', inputType: 'textarea',
            autosize: { minRows: 2, maxRows: 6 },
            label: k('remark'), placeholder: k('remark_required'),
            clearable: true, style: { width: '90%' } }
        ]
      ]
    }
  },

  created () {
    this.columns = useTableColumns([
      { prop: 'sort', label: this.key('sort'), width: 80 },
      { prop: 'code', label: this.key('code'), minWidth: 120 },
      { prop: 'name', label: this.key('name'), minWidth: 120 },
      { prop: 'remark', label: this.key('remark') },
      { prop: '_actions', label: this.key('operation'), width: 160, fixed: 'right' }
    ])
    const btns = useTableButtons({
      toolbar: [
        { key: 'add', label: this.key('add'), icon: 'el-icon-plus', type: 'primary',
          auth: '/production_master_data/factory_model/factory_area/create',
          onClick: this.openAdd }
      ],
      row: [
        { key: 'edit', label: this.key('edit'), icon: 'el-icon-edit',
          auth: '/production_master_data/factory_model/factory_area/edit',
          onClick: this.openEdit },
        { key: 'delete', label: this.key('delete'), icon: 'el-icon-delete',
          color: 'danger',
          auth: '/production_master_data/factory_model/factory_area/delete',
          onClick: this.handleDelete }
      ]
    }, this.$permission)
    this.toolbarButtons = btns.toolbarButtons
    this.rowButtons = btns.rowButtons
    this.fetchData()
  },

  methods: {
    async fetchData () {
      this.loading = true
      try {
        const res = await getFactoryAreaList({
          ...this.search, page_no: this.pagination.current, page_size: this.pagination.size
        })
        this.tableData = res.data || []
        this.pagination.total = res.count || 0
      } finally { this.loading = false }
    },

    onSearch () { this.pagination.current = 1; this.fetchData() },
    onReset () { this.search = { code: '', name: '' }; this.pagination.current = 1; this.fetchData() },
    onPageChange (page) {
      this.pagination.current = page.current
      this.pagination.size = page.size
      this.fetchData()
    },
    onSelect (rows) { this.selectedRows = rows },

    resetForm () { this.formData = { code: '', name: '', remark: '' }; this.editId = '' },

    openAdd () {
      this.handleType = 'create'
      this.dialogTitle = this.key('add_title')
      this.$nextTick(() => {
        this.$refs.dialogForm && this.$refs.dialogForm.reset()
        this.resetForm()
        this.dialogVisible = true
      })
    },

    openEdit (row) {
      this.handleType = 'edit'
      this.dialogTitle = this.key('edit_title')
      this.editId = row.id
      this.formData = { code: row.code, name: row.name, remark: row.remark || '' }
      this.dialogVisible = true
    },

    async onDialogSubmit () {
      this.submitting = true
      try {
        if (this.handleType === 'create') {
          await createFactoryArea(this.formData)
        } else {
          await editFactoryArea({ ...this.formData, id: this.editId })
        }
        this.$message.success(this.$t(this.key('operation_success')))
        this.dialogVisible = false
        this.fetchData()
      } finally { this.submitting = false }
    },

    onDialogClose () { this.resetForm() },

    async handleDelete (row) {
      try {
        await this.$confirm(
          this.$t(this.key('confirm_delete')),
          this.$t(this.key('tip')),
          { confirmButtonText: this.$t(this.key('confirm')),
            cancelButtonText: this.$t(this.key('cancel')),
            type: 'warning', closeOnClickModal: false }
        )
        await deleteFactoryArea({ id: [row.id] })
        this.$message.success(this.$t(this.key('operation_success')))
        this.pagination.current = Math.min(
          this.pagination.current,
          Math.ceil((this.pagination.total - 1) / this.pagination.size) || 1
        )
        this.fetchData()
      } catch (e) { /* 取消删除 / 请求失败不处�?*/ }
    }
  }
}
```

---

## 3. 组件 API 参�?
### 3.1 `page-table` �?表格 + 按钮�?+ 分页

#### Props

| Prop | 类型 | 默认�?| 说明 |
|------|------|--------|------|
| `columns` | `Array` | `[]` | 列定义，�?`useTableColumns()` 生成 |
| `data` | `Array` | `[]` | 表格行数�?|
| `loading` | `Boolean` | `false` | 是否显示 loading 遮罩 |
| `height` | `String/Number` | �?| 表格高度。不传则随内容撑开；传具体数值固定高度；�?`'auto'` 启用自适应 |
| `auto-height` | `Boolean` | `false` | 启用高度自适应，表格自动填满可用空�?|
| `border` | `Boolean` | `true` | 是否带边�?|
| `row-key` | `String` | `'id'` | 行唯一 key |
| `toolbar-buttons` | `Array` | `[]` | 顶部工具栏按钮，�?`useTableButtons()` 生成 |
| `row-buttons` | `Array` | `[]` | 行内操作按钮，由 `useTableButtons()` 生成 |
| `pagination` | `Object` | `null` | 分页参数 `{ current, size, total }`，传了才显示分页 |
| `table-attrs` | `Object` | `{}` | 额外透传�?`el-table` 的属�?|
| `table-listeners` | `Object` | `{}` | 额外透传�?`el-table` 的事�?|
| `help-url` | `String` | `''` | 帮助文档跳转 URL。传了才显示工具栏右侧的问号按钮，点击新窗口打开 |
| `help-text` | `String` | `'帮助'` | 帮助按钮文字，支�?i18n key（组件自�?`$t()` 翻译�?|

#### 事件

| 事件�?| 参数 | 说明 |
|--------|------|------|
| `@page-change` | `{ current, size, total }` | 分页变化（切换页�?条数�?|
| `@selection-change` | `rows: Array` | 选中行变�?|
| `@sort-change` | 透传 el-table 原生事件 | 排序变化 |

#### 插槽

| 插槽�?| 作用�?| 说明 |
|--------|--------|------|
| `#col-{prop}` | `{ row, index }` | 自定义列的渲染（列定义中 prop 需�?`slot: true`�?|
| `#toolbar-extra` | �?| 工具栏区域追加自定义内容 |
| `#empty` | �?| 表格空数据时的占�?|
| `#append` | �?| 表格最后一行后追加 |
| `#extra` | �?| 页面底部追加区域 |

#### 列定义规�?
```js
// 普通列
{ prop: 'code', label: '编码', minWidth: 120 }

// 操作列（约定：prop === '_actions'�?{ prop: '_actions', label: '操作', width: 160, fixed: 'right' }

// 自定义插槽列（slot: true�?{ prop: 'status', label: '状�?, slot: true, width: 100 }

// 复选框�?+ 序号列（通过 useTableColumns 第二个参数）
useTableColumns([...], { selectionWidth: 55, indexWidth: 60 })
```

---

### 3.2 `page-dialog-form` �?增删改查弹框

#### Props

| Prop | 类型 | 默认�?| 说明 |
|------|------|--------|------|
| `visible` | `Boolean` | `false` | 弹框显隐，使�?`.sync` 修饰�?|
| `title` | `String` | `''` | 弹框标题，支�?i18n key |
| `width` | `String` | `'35%'` | 弹框宽度 |
| `form-cols` | `Array` | `[]` | 表单字段结构（二维数组，见下方） |
| `form-data` | `Object` | `{}` | 表单数据对象 |
| `rules` | `Object` | `{}` | 校验规则，与 `el-form` rules 一�?|
| `label-width` | `String` | `'100px'` | label 宽度 |
| `submitting` | `Boolean` | `false` | 提交 loading 状�?|
| `confirm-text` | `String` | `'确定'` | 确定按钮文字 |
| `cancel-text` | `String` | `'取消'` | 取消按钮文字 |

#### 事件

| 事件�?| 说明 |
|--------|------|
| `@submit` | 表单验证通过后触发，父组件执行提交逻辑 |
| `@close` | 弹框关闭后触�?|

#### 方法（通过 ref 调用�?
| 方法 | 说明 |
|------|------|
| `reset()` | 重置表单 |
| `validate()` | 手动验证，返�?`Promise<boolean>` |

#### formCols 数据结构

**注意：需�?`data()` 中用 `k(prop)` 提前完成 i18n 翻译**，不要传 raw key�?
```js
// 例：两个普通输入框 + 一个多行文本框
formCols: [
  [
    { type: 'input', prop: 'code',
      label: k('code'), placeholder: k('enter_code'),
      clearable: true, style: { width: '90%' } }
  ],
  [
    { type: 'input', prop: 'name',
      label: k('name'), placeholder: k('enter_name'),
      clearable: true, style: { width: '90%' } }
  ],
  [
    { type: 'input', prop: 'remark', inputType: 'textarea',
      autosize: { minRows: 2, maxRows: 6 },
      label: k('remark'), placeholder: k('remark_required'),
      clearable: true, style: { width: '90%' } }
  ]
]
```

**字段支持的属性：**

| 属�?| 适用类型 | 说明 |
|------|---------|------|
| `type` | 全部 | `'input'`（文本输入）/ `'select'`（下拉） |
| `prop` | 全部 | 绑定 `formData` 中的 key |
| `label` | 全部 | 表单项标�?|
| `placeholder` | 全部 | 占位提示 |
| `inputType` | `input` | `'textarea'` 多行 / 不传为普�?text |
| `autosize` | `input` | textarea �?`{ minRows, maxRows }` |
| `clearable` | 全部 | 是否可清空，默认 `true` |
| `style` | 全部 | 样式对象 |
| `options` | `select` | 选项数组 `[{ label, value }]` |
| `filterable` | `select` | 是否可搜索，默认 `true` |

---

## 4. Composable API 参�?
### 4.1 `useTableColumns(rawColumns, options?)`

**作用**：消除手动分�?`idx` 序号，自动识别操作列和插槽列�?
| 参数 | 类型 | 默认�?| 说明 |
|------|------|--------|------|
| `rawColumns` | `Array` | �?| 列定�?|
| `options.selectionWidth` | `number` | `55` | 复选框列宽，传 `0` 隐藏 |
| `options.indexWidth` | `number` | `0` | 序号列宽，传 `0` 隐藏 |

```js
const columns = useTableColumns([
  { prop: 'code', label: '编码', width: 120 },
  { prop: 'name', label: '名称' },
  { prop: '_actions', label: '操作', width: 160, fixed: 'right' }  // �?操作�?])
```

**内部约定**：`prop === '_actions'` 自动标记�?`slot: '_actions'`，由 `page-table` 渲染为操作列�?
---

### 4.2 `useTableButtons(options, permissionCheck?)`

**作用**：统一生成工具栏按钮和行内操作按钮，自动注入权限校验结果�?
| 参数 | 类型 | 说明 |
|------|------|------|
| `options.toolbar` | `Array` | 顶部按钮列表 |
| `options.row` | `Array` | 行内按钮列表 |
| `permissionCheck` | `Function` | 权限函数，通常�?`this.$permission` |

**返回�?*：`{ toolbarButtons, rowButtons }`

**按钮字段�?*

| 字段 | toolbar | row | 说明 |
|------|:---:|:---:|------|
| `key` | �?| �?| 唯一标识 |
| `label` | �?| �?| 显示文本 |
| `icon` | �?| �?| Element UI 图标 |
| `type` | �?| �?| `primary`/`success`/`warning`/`danger` |
| `color` | �?| �?| `'danger'` 使文字变�?|
| `auth` | �?| �?| 权限 key |
| `cssStyle` | �?| �?| 自定义样�?|
| `onClick` | �?| �?| 点击回调 |
| `hasPermission` | �?| �?| **自动注入**，由权限函数计算 |
| `needSelection` | �?| �?| 需选中行才能点�?|

```js
const btns = useTableButtons({
  toolbar: [
    { key: 'add', label: '新增', icon: 'el-icon-plus', type: 'primary',
      auth: '/xxx/create', onClick: this.openAdd }
  ],
  row: [
    { key: 'edit', label: '编辑', icon: 'el-icon-edit',
      auth: '/xxx/edit', onClick: this.openEdit },
    { key: 'delete', label: '删除', icon: 'el-icon-delete',
      color: 'danger', auth: '/xxx/delete', onClick: this.handleDelete }
  ]
}, this.$permission)
```

---

### 4.3 `i18nMixin(prefix)`

**作用**：注�?`key(suffix)` �?`ckey(suffix)` 两个方法，消除每个页面手�?`T` 常量�?`tkey` 方法�?
| 方法 | 返回�?| 说明 |
|------|--------|------|
| `key(suffix)` | `prefix.suffix` | 当前页面�?i18n key |
| `ckey(suffix)` | `page.common.suffix` | 公共 i18n key（如"帮助"�?确定"�?取消"�?|

| 参数 | 类型 | 说明 |
|------|------|------|
| `prefix` | `String` | 该页面的 i18n key 前缀，如 `'page.production_master_data.factory_model.factory_area'` |

```js
import { i18nMixin } from '@/composables/useI18n'

export default {
  mixins: [i18nMixin('page.production_master_data.factory_model.factory_area')],
  // 此后模板中用 $t(key('code')) 访问当前页面的翻�?  // �?$t(ckey('help')) 访问公共翻译 'page.common.help'
  // JS 中用 this.$t(this.key('code')) / this.$t(this.ckey('help'))
}
```

**`data()` 中翻译文本的技�?*�?
```js
data () {
  const t = this.$t.bind(this)       // 绑定 i18n 翻译函数
  const k = (s) => t(this.key(s))   // 当前页面翻译：key + translate
  const ck = (s) => t(this.ckey(s)) // 公共翻译：ckey + translate

  return {
    formCols: [
      [{ label: k('code'), placeholder: k('enter_code') }]  // 页面�?key
    ],
    helpText: ck('help')  // 公共 key
  }
}
```

---

## 5. i18n 国际化方�?
### 5.1 语言包文�?
| 语言 | 文件路径 |
|------|---------|
| 简体中�?| `src/locales/zh-chs.json` |
| 繁体中文 | `src/locales/zh-cht.json` |
| 英文 | `src/locales/en.json` |
| 日文 | `src/locales/ja.json` |

### 5.2 语言包结�?
�?`一级模�?�?二级模块 �?三级模块` 三层嵌套�?
```json
{
  "page": {
    "production_master_data": {
      "factory_model": {
        "factory_area": {
          "search": "查询",
          "reset": "重置",
          "code": "所区编�?,
          "name": "所区名�?,
          "add": "�?�?,
          "edit": "�?�?,
          "delete": "�?�?,
          "enter_code": "请输入所区编�?,
          "enter_name": "请输入所区名�?,
          "add_title": "新增所�?,
          "edit_title": "编辑所�?,
          "confirm": "确定",
          "cancel": "取消",
          "operation_success": "操作成功"
        }
      }
    }
  }
}
```

### 5.3 组件自动翻译

`page-table` �?`page-dialog-form` 内置 `$t()`�?
- **�?label** �?自动翻译
- **按钮 label** �?自动翻译
- **表单 label / placeholder** �?自动翻译
- **弹框 title / confirm / cancel** �?自动翻译

因此页面只需传入 i18n key 字符串，组件渲染时自动替换为当前语言的文本�?
### 5.4 页面中手动翻�?
搜索区、校验消息、`$confirm` �?UI 文字需手动�?`$t()`�?
```vue
<!-- 模板�?�?key() 返回 i18n key -->
<el-form-item :label="$t(key('code'))">
  <el-input :placeholder="$t(key('enter_code'))" />
</el-form-item>
<el-button>{{ $t(key('search')) }}</el-button>
```

```js
// JS �?this.$message.success(this.$t(this.key('operation_success')))
this.$confirm(this.$t(this.key('confirm_delete')), this.$t(this.key('tip')), { ... })
```

---

## 6. 常用场景速查

### 场景 1：自定义列渲染（状�?tag�?
列定义加�?`slot: true`�?
```js
useTableColumns([
  { prop: 'status', label: '状�?, slot: true, width: 100 }
])
```

模板中用 `#col-status` 插槽�?
```vue
<page-table :columns="columns" :data="tableData">
  <template #col-status="{ row }">
    <el-tag :type="row.status === 1 ? 'success' : 'danger'">
      {{ row.status === 1 ? '启用' : '禁用' }}
    </el-tag>
  </template>
</page-table>
```

### 场景 2：工具栏追加自定义按�?
```vue
<page-table :columns="columns" :toolbar-buttons="toolbarButtons">
  <template #toolbar-extra>
    <el-button size="mini" icon="el-icon-printer" @click="print">打印</el-button>
  </template>
</page-table>
```

### 场景 3：复选框�?+ 序号�?
```js
useTableColumns(
  [
    { prop: 'code', label: '编码' },
    { prop: 'name', label: '名称' }
  ],
  { selectionWidth: 55, indexWidth: 60 }
)
```

### 场景 4：带下拉选择的表�?
```js
formCols: [
  [
    { type: 'select', prop: 'area_id',
      label: k('area'), placeholder: k('select_area'),
      options: [{ label: 'A厂区', value: 1 }, { label: 'B厂区', value: 2 }],
      clearable: true, style: { width: '90%' } }
  ]
]
```

### 场景 5：批量删除（工具�?+ 需要选中行）

```js
useTableButtons({
  toolbar: [
    { key: 'batchDelete', label: '批量删除', icon: 'el-icon-delete',
      type: 'danger', auth: '/xxx/batch-delete',
      needSelection: true,  // �?需要选中行才能点�?      onClick: this.batchDelete }
  ]
})
```

### 场景 6：表格自适应高度

只需�?`auto-height` 属性：

```vue
<page-table ... auto-height />
```

表格高度会自动填�?`d2-container` �?body 区域剩余空间，窗�?resize / 侧栏折叠时自动重算�?
### 场景 7：帮助按�?
�?`help-url` 传值即可在工具栏最右侧显示问号帮助按钮，点击在新窗口打开帮助文档�?
```vue
<page-table ... help-url="/help/factory-area" :help-text="$t(ckey('help'))" />
```

按钮文字通过 `help-text` prop 支持 i18n。推荐使用公�?key `page.common.help`（模板中�?`$t(ckey('help'))`），所有页面共享，无需每个模块重复定义�?
不传 `help-url` 或传空字符串则不显示帮助按钮�?
---

## 7. 路由配置

```js
// src/router/modules/production-master-data.js
import layoutHeaderAside from '@/layout/header-aside'

const meta = { auth: true }
const _import = require('@/libs/util.import.' + process.env.NODE_ENV)

export default {
  path: '/production_master_data',
  component: layoutHeaderAside,
  children: (pre => [
    {
      path: 'factory_model/factory_area',
      name: `${pre}factory_model-factory_area`,
      meta: { ...meta, cache: true, title: '工厂区域' },
      component: _import('production-master-data/factory-model/factory-area')
    }
  ])('production_master_data-')
}
```

之后�?`src/router/routes.js` 中引入该模块并加�?`frameIn` 数组�?
```js
import productionConfiguration from './modules/production-master-data'

const frameIn = [
  // ... 其他路由 ...
  productionConfiguration
]
```

---

## 8. API 文件写法

```js
// src/api/production-master-data/factory-area.js
import { request } from '@/api/_service'

const BASE = 'production_master_data/factory_model/factory_area/'

function apiParams (method, data = {}) {
  return {
    method: `production_master_data_factory_model_factory_area_${method}`,
    platform: 'background',
    ...data
  }
}

export function getFactoryAreaList (data) {
  return request({
    url: BASE + 'list',
    method: 'get',
    params: apiParams('list', data)
  })
}

export function createFactoryArea (data) {
  return request({
    url: BASE + 'create',
    method: 'post',
    data: apiParams('create', data)
  })
}

export function editFactoryArea (data) {
  return request({
    url: BASE + 'edit',
    method: 'put',
    data: apiParams('edit', data)
  })
}

export function deleteFactoryArea (data) {
  return request({
    url: BASE + 'delete',
    method: 'delete',
    data: apiParams('delete', data)
  })
}
```

---

## 9. 旧代码迁移对�?
| 旧写�?| 新写�?|
|--------|--------|
| 手动构建 `columns: [{ idx: 0, attrs: { prop, label } }]` | `useTableColumns([{ prop, label }])` |
| `buttonList: [...]` + `tableButtonList: [...]` 分两�?| `useTableButtons({ toolbar: [...], row: [...] })` |
| `<sct-base-table>` + `<sct-base-dialog>` + `<SctBaseForm>` 三层 | `<page-table>` + `<page-dialog-form>` 两层 |
| `<sct-form-search>` 组件 | 原生 `<el-form :inline>` |
| `<sct-back-to-top>` 组件 | 需要时自行添加 |
| 分页需要额�?`<page-footer>` | `page-table` 内置分页 |
| 每个页面定义 `T` 常量 + `tkey()` 方法 | `mixins: [i18nMixin(prefix)]`，使�?`this.key('xxx')` |
| 表单字段�?i18n raw key，子组件翻译 | `data()` 中用 `k(prop)` 提前翻译 |

---

## 10. 常见问题排查

### Q1：弹框打开后不显示内容�?
确认 `formCols` 中的 `label` �?`placeholder` 是否�?`data()` 阶段已翻译。子组件 `page-dialog-form` 会调�?`$t()` 处理 label，但建议�?`data()` 阶段就用 `k()` 提前翻译好，避免 webpack HMR 缓存问题�?
### Q2：表格高度自适应不生效？

确认 `d2-container` �?body 区域高度被正确约束（flex 填充）。如�?`d2-container` 本身�?`overflow: auto` 或其他高度约束问题，`page-table` �?`height: 100%` 会失效。给 `d2-container` �?body 部分�?`overflow: hidden` 通常可解决�?
### Q3：权限校验有按钮不显示？

`useTableButtons` 的第二个参数必须�?`this.$permission`。如果项目没有注册这个全局方法，可以在 `useTableButtons` 中传入一个返�?`true` 的占位函数：`() => true`�?
### Q4：新增一条后页码不跳回第一页？

�?`onDialogSubmit` 成功后调�?`this.fetchData()` 前，如果删除了当前页最后一行导�?`total - 1` 超出范围，需手动修正页码�?
```js
this.pagination.current = Math.min(
  this.pagination.current,
  Math.ceil((this.pagination.total - 1) / this.pagination.size) || 1
)
```

### Q5：表单验证不提示错误文字�?
确认 `page-dialog-form` �?`<style>` 块存在（默认 22px `margin-bottom` + `position: absolute` 错误文字）。如果表单项之间被其他样式覆盖，检查是否有全局 CSS 重置�?`.el-form-item` �?margin�?
### Q6：如何新增一�?CRUD 页面最快？

1. 复制 `src/views/production-master-data/factory-model/factory-area/index.vue`
2. 替换 API 引用（`import { getList, create, edit, ... } from '@/api/xxx'`�?3. 修改 `i18nMixin` 参数、`columns`、`formCols`、`rules`
4. �?`zh-chs.json` �?`en.json` 中添加语言�?5. 添加路由配置

平均 10 分钟即可完成一个标�?CRUD 页面�?