DataTables
進階互動
表格功能。
Editor
DataTables 的
完整編輯函式庫。
手冊
下載
{hero}
≡ 顯示網站導覽

stateRestoreConfig

StateRestore 按鈕的組態選項。
請注意 - 此屬性需要 DataTables 的 StateRestore 擴充套件。

說明

許多 StateRestore 按鈕都共用一些選項，可用於設定它們的行為以及與表格的互動方式。例如，可以將按鈕設定為透過 Ajax 載入資料。此處定義了按鈕可用的選項。

選項

  • ajax - 設定透過 Ajax 載入和儲存狀態
  • create - 啟用/停用建立新狀態
  • creationModal - 在建立時顯示一個模態視窗，允許自訂狀態
  • preDefined - 在 DataTables 初始化中設定預先定義的狀態
  • remove - 啟用/停用移除狀態
  • rename - 啟用/停用重新命名狀態
  • save - 啟用/停用更新狀態
  • saveState - 啟用/停用儲存各種 DataTables 元素
  • splitSecondaries - 設定將在 StateRestore 分割下拉式選單中顯示的分割按鈕
  • toggle - 啟用/停用儲存新狀態時儲存各種 DataTables 元素。

ajax

此選項允許 StateRestore 透過 Ajax 載入和儲存狀態。如果為此選項提供的值是字串，StateRestore 將會使用它作為透過 Ajax 發出請求的目的地 URL。

將值設定為函式，可讓使用者在將狀態載入 StateRestore、重新命名、移除或儲存狀態時自訂行為。函式的行為沒有任何限制，您可以在呼叫此函式時執行任何您想執行的操作。

預設值為 false，表示狀態將會儲存在本機工作階段儲存空間中。將此選項的值設定為 true 無效。

此範例展示了 ajax 選項的實際應用。

預設情況下，此選項已停用 (false)。

值 (字串)

當 StateRestore 要嘗試使用 Ajax 載入和儲存狀態時，應將此選項設定為字串。此字串應為 URL，以告知 StateRestore 應將請求發送到哪裡。

值 (函式)

每當以下情況發生時，都會呼叫此函式

  • 狀態載入 StateRestore
  • 狀態被重新命名
  • 狀態被移除
  • 狀態被儲存

它接受兩個參數

第一個是 data，其中包含處理動作所需的所有資料。第二個是回呼函式，當透過 Ajax 函式載入狀態時，應該呼叫此函式。能夠將此選項設定為函式，可讓使用者在如何儲存其狀態方面有更大的彈性。

1) 將透過 Ajax 傳遞的相關資料。物件包含 2 個屬性。

  • action 字串 導致 Ajax 呼叫發生的動作類型。為 load、rename、remove 或 save 其中之一。
  • stateRestore 物件 此物件包含一個屬性，對應於每一個受呼叫影響的狀態。在進行儲存或移除時，該值應為其應儲存的狀態物件。在重新命名時，此值會略有不同，其值應為覆寫對應鍵值的新名稱。載入狀態時，不會出現此屬性。

2) 一個回呼函式，可以根據所執行的動作執行兩種不同的目的。

在第一種情況下，透過 Ajax 函式將預先定義的狀態載入 StateRestore 時。在這種情況下，data.action 屬性將會設定為 load。它接受單一引數，其結構應與 preDefined 相同。

對於所有其他可能的動作，必須在動作已成功執行時執行此回呼。在這種情況下，它不接受任何額外參數。

不預期有傳回值。

範例

此範例設定 StateRestore 將請求傳送到的 Ajax URL

new DataTable('#myTable', {
    ajax: {
        url: '../data/2500States.txt',
        dataSrc: 'data'
    },
    layout: {
        topStart: {
            buttons: [
                'createState',
                {
                    extend: 'savedStates',
                    config: {
                        ajax: '/api/stateControllers/stateRestore'
                    }
                }
            ]
        }
    }
});
````



## create

This option allows for the creation of states to be enabled or disabled.

As default the value is `true`, meaning that states can be created. If this option is set to `false`, then creation will be disabled.

It is also worth noting that if [`save`](#save) is set to `false`, the value set here will be overruled. This is because creation is a form of saving, and is therefore disabled when that option is.

Take a look at [this example](/extensions/staterestore/examples/initialisation/noCreation.html) to see this in action. In this example the configuration takes place in the `-button savedStates` button. This is because we want to block creation via the api, without having to show the `-button createState` button.


### Value (boolean)

This property should be set to a boolean value. `true` if creation is to be enabled (default), `false` if not.


### Example

This example shows the ability to create new states being disabled:

```js
new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                {
                    extend: 'savedStates',
                    config: {
                        create: false
                    }
                }
            ]
        }
    }
});

creationModal

此選項允許向使用者顯示建立模態視窗。這可讓他們在初始化時設定自訂狀態名稱，並自訂新狀態中儲存的 DataTables 元素。這是透過設定 toggle 選項來完成的。

值 (布林值)

此屬性應設定為布林值。當此選項設定為 true 時，會在建立時向使用者顯示一個模態視窗，允許他們自訂將要儲存的狀態。如果值設定為 false (預設值)，則不會顯示建立模態視窗。在這種情況下，會自動產生名稱，並將所有支援狀態儲存的 DataTables 元素儲存在新的狀態中。

範例

此範例啟用建立模態視窗顯示

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                'createState',
                {
                    extend: 'savedStates',
                    config: {
                        creationModal: true
                    }
                },
                'colvis'
            ]
        }
    }
});

此範例使用切換選項啟用建立模態視窗

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                {
                    extend: 'createState',
                    config: {
                        creationModal: true,
                        toggle: {
                            columns: {
                                search: true,
                                visible: true
                            },
                            length: true,
                            order: true,
                            paging: true,
                            scroller: true,
                            search: true,
                            searchBuilder: true,
                            searchPanes: true,
                            select: true
                        }
                    }
                },
                'savedStates',
                'colvis'
            ]
        }
    }
});

preDefined

此選項允許 StateRestore 載入 DataTables 初始化中設定的預先定義狀態。此物件包含鍵值對，其中鍵為識別碼，值為要重新載入的狀態。可以使用 state() 方法隨時從 DataTable 擷取此資訊。

預設值為空物件，表示不會將預先定義的狀態載入 StateRestore 中。

請查看 此範例以查看實際應用。

值 (物件)

preDefined 選項的預設值為 {}，表示標準情況下沒有預先定義的狀態。

定義時，物件鍵為狀態的識別碼，值為要重新載入的狀態。可以使用 state() 方法隨時從 DataTable 擷取此值。

預先定義狀態的對應值結構如下。

  • 數字 start - 應顯示的第一列。
  • 數字 length - 每頁應顯示的列數。
  • 陣列 order - 應套用到表格的排序。此值與 order 初始化選項中使用的值相同。
  • 物件 search - 這是一個包含搜尋詳細資訊的物件。此值與 search 初始化選項中使用的值相同。
  • 陣列 columns - 這是一個物件陣列，每個欄位一個物件。它具有兩個屬性。
    • columns.visible - 此值與初始化選項 columns.visible 相同，true 表示顯示，false 表示隱藏。
    • columns.search - 這也會採用與 columns.search 初始化選項相同的值。
  • 物件 scroller - 此物件包含四個屬性。
    • 數字 baseRowTop - 以列為單位表示捲動條捲動的距離。例如，10.5 會將顯示的表格頂部設定為距離頂部 10.5 列的位置。
    • 數字 topRow - 此值與 baseRowTop 相同。
    • 數字 baseScrollTop - 以像素為單位表示捲動條捲動的距離。
    • 數字 scrollTop - 此值與 baseScrollTop 相同。
  • 物件 searchBuilder - 此值與從 searchBuilder.getDetails() 傳回的值相同。
  • 物件 searchPanes - 此物件包含重新建構先前的 SearchPanes 所需的詳細資訊。並非所有下列資料都需要在 SearchPanes 中進行選取。為此，只需要 selectionList 屬性。
    • 陣列 panes - 此陣列包含每個顯示窗格的物件。這些物件包含重新載入資料以及設定每個 SearchPane 所需的詳細資訊。
      • 陣列 arrayFilter 這是一個陣列，其中包含每個將在 SearchPane 中顯示的選項的物件。
        • 字串 display - 這是顯示在 SearchPane 中的字串值。
        • string filter - 這是用於在 SearchPane 上篩選的字串值。
        • string sort - 這是用於在 SearchPane 上排序的字串值。
        • string type - 這是用於在 SearchPane 上判斷類型的字串值。
      • object bins - 此物件包含此窗格欄位中每個不同值的鍵值對。鍵是不同的值，值是該值在欄位中出現的次數。
      • boolean collapsed - 此窗格在上次儲存狀態時是否為摺疊狀態。
      • number id - 窗格的 ID，對應於其所附加的欄位索引。
    • array selectionList - 此陣列包含每個顯示的窗格的物件。這些物件包含每個窗格中所選取的詳細資料。
      • number column - 選擇所附加到的窗格索引。
      • array rows - 此陣列包含要選擇的篩選值。
  • object select - 此物件包含 3 個屬性，這些屬性是進行先前選取所必需的。
    • array rows - 此陣列包含要選取之列的所有列 ID。它與從 rows().ids() 傳回的值相同。
    • array columns - 此陣列包含要選取之欄的欄索引。
    • array cells - 此陣列包含每個都具有兩個屬性的物件。這些屬性指示應選取哪個儲存格。
      • string row - 要選取之儲存格的列 ID。
      • number column - 要選取之儲存格的欄索引。

範例

此範例為 StateRestore 設定一個預先定義的狀態，該狀態會在使用者首次載入頁面時顯示給他們

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                'createState',
                {
                    extend: 'savedStates',
                    config: {
                        preDefined: {
                            'Order 3': {
                                start: 0,
                                length: 10,
                                order: [[1, 'asc']],
                                search: {
                                    search: '',
                                    smart: true,
                                    regex: false,
                                    caseInsensitive: true
                                },
                                columns: [
                                    {
                                        visible: true,
                                        search: {
                                            search: '',
                                            smart: true,
                                            regex: false,
                                            caseInsensitive: true
                                        }
                                    },
                                    {
                                        visible: true,
                                        search: {
                                            search: '',
                                            smart: true,
                                            regex: false,
                                            caseInsensitive: true
                                        }
                                    },
                                    {
                                        visible: true,
                                        search: {
                                            search: '',
                                            smart: true,
                                            regex: false,
                                            caseInsensitive: true
                                        }
                                    },
                                    {
                                        visible: true,
                                        search: {
                                            search: '',
                                            smart: true,
                                            regex: false,
                                            caseInsensitive: true
                                        }
                                    },
                                    {
                                        visible: true,
                                        search: {
                                            search: '',
                                            smart: true,
                                            regex: false,
                                            caseInsensitive: true
                                        }
                                    },
                                    {
                                        visible: true,
                                        search: {
                                            search: '',
                                            smart: true,
                                            regex: false,
                                            caseInsensitive: true
                                        }
                                    }
                                ]
                            }
                        }
                    }
                }
            ]
        }
    }
});

移除

此選項允許啟用或停用狀態的移除。

請查看此範例，以了解其實際運作方式。

值 (布林值)

此選項的預設值為 true，表示預設會啟用移除狀態。設定為 false 則停用。

範例

停用新狀態的移除

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                'createState',
                {
                    extend: 'savedStates',
                    config: {
                        remove: false
                    }
                }
            ]
        }
    }
});

重新命名

此選項允許啟用或停用狀態的重新命名。

還值得注意的是，如果 save 設定為 false，則此處設定的值將被覆寫。這是因為重新命名是一種儲存形式，因此在該選項停用時也會停用。

請查看此範例，以了解其實際運作方式。

值 (布林值)

此選項的預設值為 true，表示預設會啟用重新命名狀態。設定為 false 則停用。

範例

停用新狀態的重新命名

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                'createState',
                {
                    extend: 'savedStates',
                    config: {
                        rename: false
                    }
                }
            ]
        }
    }
});

儲存

此選項允許啟用或停用狀態的儲存。

預設值為 true，表示可以儲存狀態。如果此選項設定為 false，則也會停用狀態的更新以及新狀態的建立，因為這也是一種儲存作業。

重要的是要注意，這不僅會影響狀態的更新，還會影響狀態的建立和重新命名。這些可以使用 create 和 rename 獨立控制，但如果此選項設定為 false，則會覆寫這兩者。這是因為建立和重新命名本身都是一種儲存形式。

請查看此範例，以了解其實際運作方式。

值 (布林值)

此選項的預設值為 true，表示預設會啟用儲存狀態。設定為 false 則停用。

範例

停用新狀態的儲存

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                {
                    extend: 'savedStates',
                    config: {
                        save: false
                    }
                }
            ]
        }
    }
});

儲存狀態

此選項決定 StateRestore 將儲存哪些內容。此選項是一個包含布林值的物件，每個可以儲存的元素都有一個布林值。這些如下（請注意，預設值都是 true）

  • columns - 容器物件
    • columns.search - 此選項允許啟用或停用儲存應用於個別欄位的搜尋。
    • columns.visible - 此選項允許啟用或停用儲存欄位的可見性。
  • length - 此選項允許啟用或停用儲存頁面長度。注意：當使用此選項並儲存包含分頁的狀態時，StateRestore 將顯示在表格開始時儲存狀態時顯示的第一列。例如，這可能會導致一個頁面長度為 50 的表格，但從記錄 31 開始。在不知道頁面長度的情況下，DataTables 無法計算任何其他起始位置。
  • order - 此選項允許啟用或停用儲存表格的欄位排序。
  • paging - 此選項允許啟用或停用儲存分頁。
  • scroller - 此選項允許啟用或停用儲存 scroller 位置。此選項僅適用於同時使用 StateRestore 和 Scroller 擴充功能時。
  • search - 此選項允許啟用或停用儲存搜尋。
  • searchBuilder - 此選項允許啟用或停用儲存 searchBuilder 狀態。此選項僅適用於同時使用 StateRestore 和 SearchBuilder 擴充功能時。
  • searchPanes - 此選項允許啟用或停用儲存 searchPanes 狀態。此選項僅適用於同時使用 StateRestore 和 SearchPanes 擴充功能時。
  • select - 此選項允許啟用或停用儲存 select 狀態。此選項僅適用於同時使用 StateRestore 和 Select 擴充功能時。

值 (物件)

此初始化選項是一個物件，其中包含各種布林值，可啟用或停用儲存 DataTable 狀態的不同元素。

範例

停用分頁儲存

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                'createState',
                {
                    extend: 'savedStates',
                    config: {
                        saveState: {
                            paging: false
                        }
                    }
                },
                'colvis'
            ]
        }
    }
});

停用欄位可見性儲存

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                'createState',
                {
                    extend: 'savedStates',
                    config: {
                        saveState: {
                            columns: {
                                visible: false
                            }
                        }
                    }
                },
                'colvis'
            ]
        }
    }
});

分割次要項目

此選項允許自訂或新增每個 StateRestore 狀態提供的按鈕。

預設值是如下所示的預設按鈕陣列。這些按鈕為 StateRestore 提供所有標準功能。當所有預設按鈕都存在時，如果將 save、rename 或 remove 設定為 false，則仍會移除對應的按鈕。

此選項的設定格式與 buttons.buttons 相同，請參閱該處的文件以取得完整詳細資料。

值 (string[])

此選項的預設值為

splitSecondaries: [
    'updateState',
    'renameState',
    'removeState'
]

這些是為 StateRestore 狀態提供功能的預設按鈕。

範例

自訂 StateRestore 狀態分割下拉式選單中保留的按鈕。

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                {
                    extend: 'savedStates',
                    config: {
                        splitSecondaries: [
                            'updateState',
                            'removeState',
                            '<h3>Custom HTML!</h3>',
                            'pdf',
                            {
                                extend: 'renameState',
                                className: 'red-border'
                            }
                        ]
                    }
                },
                'createState'
            ]
        }
    }
});

切換

此選項允許使用者指定在建立新狀態時應儲存哪些元素。此選項是一個包含布林值的物件，每個可以儲存的元素都有一個布林值。當設定為 true 時，會在建立模式中顯示對應元素的核取方塊，讓使用者決定是否應該儲存該元素。

對於支援狀態儲存的擴充功能，如果不存在該擴充功能，則無論此處的對應值為何，都不會顯示切換選項。

為了顯示建立模式，必須將 creationModal 設定為 true。

值 (物件)

此選項的預設值是與 saveState 選項格式相同的物件。這將允許使用者為每個支援狀態儲存的 DataTables 元素設定要儲存的內容。預設值為

{
    columns: {
        search: false,
        visible: false
    },
    order: false,
    paging: false,
    scroller: false,
    search: false,
    searchBuilder: false,
    searchPanes: false,
    select: false
}

範例

啟用分頁儲存自訂

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                {
                    extend: 'createState',
                    config: {
                        toggle: {
                            paging: true
                        }
                    }
                },
                'savedStates',
                'colvis'
            ]
        }
    }
});
頁面導覽

DataTables

DataTables 由 SpryMedia Ltd 設計和建立。
© 2007-2024 MIT 授權。 隱私權政策。 支持者。
SpryMedia Ltd 在蘇格蘭註冊，公司編號為 SC456502。