# 導入導出操作 ### 介紹 **導入導出行為**是一個控制器修改器，提供了用于導入和導出數據的功能。該行為提供了兩個頁面，分別稱為“導入”和“導出”。導入頁面允許用戶上載CSV文件并將列與數據庫匹配。導出頁面則相反，它允許用戶從數據庫下載列作為CSV文件。該行為提供了控制器動作`import()`和`export()`。 行為配置分為兩部分，每部分都取決于一個特殊的模型類以及一個列表和表單字段定義文件。要使用導入和導出行為，應將其添加到`$implement`控制器類的屬性中。另外，`$importExportConfig`應該定義class屬性，并且其值應引用用于配置行為選項的YAML文件。 ~~~ namespace Acme\Shop\Controllers; class Products extends Controller { public $implement = [ 'Backend.Behaviors.ImportExportController', ]; public $importExportConfig = 'config_import_export.yaml'; // [...] } ~~~ ### [](https://octobercms.com/docs/backend/import-export#configuring-import-export)配置行為 `$importExportConfig`屬性中引用的配置文件以YAML格式定義。該文件應放置在控制器的[views目錄中](https://octobercms.com/docs/backend/controllers-ajax/#introduction)。以下是配置文件的示例： ~~~ # =================================== # Import/Export Behavior Config # =================================== import: title: Import subscribers modelClass: Acme\Campaign\Models\SubscriberImport list: $/acme/campaign/models/subscriber/columns.yaml export: title: Export subscribers modelClass: Acme\Campaign\Models\SubscriberExport list: $/acme/campaign/models/subscriber/columns.yaml ~~~ 下面列出的配置選項是可選的。如果您希望行為支持[Import](https://octobercms.com/docs/backend/import-export#import-page)或[Export](https://octobercms.com/docs/backend/import-export#export-page)或同時支持兩者，請定義它們。 | 選項 | 描述 | | --- | --- | | **defaultRedirect** | 未定義特定重定向頁面時，用作后備重定向頁面。 | | **import** | 導入頁面的配置數組或對配置文件的引用。 | | **export** | 導出頁面的配置數組或對配置文件的引用。 | | **defaultFormatOptions** | 默認CSV格式選項的配置數組或對配置文件的引用。 | ### [](https://octobercms.com/docs/backend/import-export#import-page)導入頁面 要支持“導入”頁面，請在YAML文件中添加以下配置： ~~~ import: title: Import subscribers modelClass: Acme\Campaign\Models\SubscriberImport list: $/acme/campaign/models/subscriberimport/columns.yaml redirect: acme/campaign/subscribers ~~~ 導入頁面支持以下配置選項： | 選項 | 描述 | | --- | --- | | **title** | 頁面標題，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 | | **list** | 定義可用于導入的列表列。 | | **form** | 提供用作導入選項的其他字段（可選）。 | | **redirect** | 導入完成后的重定向頁面，可選 | | **permissions** | 執行操作所需的用戶權限，可選 | ### [](https://octobercms.com/docs/backend/import-export#export-page)導出頁面 要支持“導出”頁面，請在YAML文件中添加以下配置： ~~~ export: title: Export subscribers modelClass: Acme\Campaign\Models\SubscriberExport list: $/acme/campaign/models/subscriberexport/columns.yaml redirect: acme/campaign/subscribers ~~~ 導出頁面支持以下配置選項： | 選項 | 描述 | | --- | --- | | **title** | 頁面標題，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 | | **fileName** | 用于導出文件的文件名，默認為**export.csv**。 | | **list** | 定義可用于導出的列表列。 | | **form** | 提供用作導入選項的其他字段（可選）。 | | **redirect** | 導出完成后的重定向頁面，可選。 | | **useList** | 設置為true或列表定義的值以啟用[與Lists的集成](https://octobercms.com/docs/backend/import-export#list-behavior-integration)，默認值：false。 | ### [](https://octobercms.com/docs/backend/import-export#format-options)格式選項 要覆蓋默認的CSV格式選項，請在YAML文件中添加以下配置： ~~~ defaultFormatOptions: delimiter: ';' enclosure: '"' escape: '\' encoding: 'utf-8' ~~~ 格式選項支持以下配置選項（所有可選）： | 選項 | 描述 | | --- | --- | | **delimiter** | 分隔符。 | | **enclosure** | 外殼字符。 | | **escape** | 轉義符。 | | **encoding** | 文件編碼（僅用于導入）。 | ### [](https://octobercms.com/docs/backend/import-export#import-export-views)導入和導出視圖 對于“[導入](https://octobercms.com/docs/backend/import-export#import-page)和[導出”的](https://octobercms.com/docs/backend/import-export#export-page)每個頁面功能，您應該提供一個具有相應名稱的[視圖文件](https://octobercms.com/docs/backend/controllers-ajax/#introduction)**\-import.htm**和**export.htm**。 導入/導出行為將兩個方法添加到控制器類：`importRender`和`exportRender`。這些方法根據上述YAML配置文件呈現導入和導出節。 ### [](https://octobercms.com/docs/backend/import-export#import-view)導入視圖 該**import.htm**視圖表示導入頁面，允許用戶導入數據。典型的“導入”頁面包含面包屑，“導入”部分本身和提交按鈕。該**數據請求**屬性應該指的是`onImport`由行為提供AJAX的處理程序。以下是典型的import.htm視圖文件的內容。 ~~~ <?= Form::open(['class' => 'layout']) ?> <div class="layout-row"> <?= $this->importRender() ?> </div> <div class="form-buttons"> <button type="submit" data-control="popup" data-handler="onImportLoadForm" data-keyboard="false" class="btn btn-primary"> Import records </button> </div> <?= Form::close() ?> ~~~ ### [](https://octobercms.com/docs/backend/import-export#export-view)匯出檢視 該**export.htm**視圖表示導出頁面，允許用戶將文件從數據庫導出。典型的“導出”頁面包含面包屑，“導出”部分本身和提交按鈕。該**數據請求**屬性應該指的是`onExport`由行為提供AJAX的處理程序。以下是典型的export.htm表單的內容。 ~~~ <?= Form::open(['class' => 'layout']) ?> <div class="layout-row"> <?= $this->exportRender() ?> </div> <div class="form-buttons"> <button type="submit" data-control="popup" data-handler="onExportLoadForm" data-keyboard="false" class="btn btn-primary"> Export records </button> </div> <?= Form::close() ?> ~~~ ### [](https://octobercms.com/docs/backend/import-export#import-model)定義導入模型 為了導入數據，您應該為此過程創建一個專用模型，以擴展`Backend\Models\ImportModel`該類。這是一個示例類定義： ~~~ class SubscriberImport extends \Backend\Models\ImportModel { /** * @var array The rules to be applied to the data. */ public $rules = []; public function importData($results, $sessionKey = null) { foreach ($results as $row => $data) { try { $subscriber = new Subscriber; $subscriber->fill($data); $subscriber->save(); $this->logCreated(); } catch (\Exception $ex) { $this->logError($row, $ex->getMessage()); } } } } ~~~ 該類必須定義一個稱為的`importData`用于處理導入數據的方法。第一個參數`$results`將包含一個數組，其中包含要導入的數據。第二個參數`$sessionKey`將包含用于請求的會話密鑰。 | 方法 | 描述 | | --- | --- | | `logUpdated()` | 記錄更新時調用。 | | `logCreated()` | 創建記錄時調用。 | | `logError(rowIndex, message)` | 導入記錄有問題時調用。 | | `logWarning(rowIndex, message)` | 用于提供軟警告，例如修改值。 | | `logSkipped(rowIndex, message)` | 未導入（跳過）整行數據時使用。 | ### [](https://octobercms.com/docs/backend/import-export#export-model)定義導出模型 為了導出數據，您應該創建一個擴展`Backend\Models\ExportModel`該類的專用模型。這是一個例子： ~~~ class SubscriberExport extends \Backend\Models\ExportModel { public function exportData($columns, $sessionKey = null) { $subscribers = Subscriber::all(); $subscribers->each(function($subscriber) use ($columns) { $subscriber->addVisible($columns); }); return $subscribers->toArray(); } } ~~~ 該類必須定義一個稱為`exportData`用于返回導出數據的方法。第一個參數`$columns`是要導出的列名稱的數組。第二個參數`$sessionKey`將包含用于請求的會話密鑰。 ### [](https://octobercms.com/docs/backend/import-export#custom-options)自訂選項 導入和導出表單均支持可使用表單字段引入的自定義選項，這些選項分別在導入或導出配置中的**表單**選項中定義。然后將這些值傳遞到導入/導出模型，并在處理期間可用。 ~~~ import: [...] form: $/acme/campaign/models/subscriberimport/fields.yaml export: [...] form: $/acme/campaign/models/subscriberexport/fields.yaml ~~~ 指定的表單字段將出現在導入/導出頁面上。這是一個示例`fields.yaml`文件內容： ~~~ # =================================== # Form Field Definitions # =================================== fields: auto_create_lists: label: Automatically create lists type: checkbox default: true ~~~ 可以使用導入模型的方法內部訪問上方名為**auto\_create\_lists**的表單字段的值。如果這是導出模型，則該值將在方法內部可用。`$this->auto_create_lists``importData``exportData` ~~~ class SubscriberImport extends \Backend\Models\ImportModel { public function importData($results, $sessionKey = null) { if ($this->auto_create_lists) { // Do something } [...] } } ~~~ ### [](https://octobercms.com/docs/backend/import-export#list-behavior-integration)與列表行為整合 有另一種導出數據的方法，該方法使用[列表行為](https://octobercms.com/docs/backend/lists)提供導出數據。為了使用此功能，您應該對控制器類`Backend.Behaviors.ListController`的`$implement`字段進行定義。您不需要使用導出視圖，所有設置將從列表中拉出。這是唯一需要的配置： ~~~ export: useList: true ~~~ 如果使用[多個列表定義](https://octobercms.com/docs/backend/lists#multiple-list-definitions)，則可以提供列表定義： ~~~ export: useList: orders fileName: orders.csv ~~~ 該`useList`選項還支持擴展配置選項。 ~~~ export: useList: definition: orders raw: true ~~~ 支持以下配置選項： | 選項 | 描述 | | --- | --- | |**definition** | 用于從中獲取記錄的列表定義（可選）。 | | **raw** | 從記錄中輸出原始屬性值，默認值：false。 |