Data Grid - 欄定義

定義您的欄。

欄使用 columns 屬性定義，其類型為 GridColDef[]。

field 是唯一必需的屬性，因為它是欄識別符。它也用於與 GridRowModel 值匹配。

interface GridColDef {
  /**
   * The column identifier. It's used to match with [[GridRowModel]] values.
   */
  field: string;
  …
}

提供內容

預設情況下，Data Grid 使用欄的 field 來取得其值。例如，field 為 name 的欄將渲染儲存在 row.name 中的值。但對於某些欄，手動取得和格式化要渲染的值可能很有用。

值 getter

有時，欄可能沒有所需的值。您可以使用 GridColDef 的 valueGetter 屬性來

轉換值

const columns: GridColDef[] = [
  {
    field: 'taxRate',
    valueGetter: (value) => {
      if (!value) {
        return value;
      }
      // Convert the decimal value to a percentage
      return value * 100;
    },
  },
];

渲染不同欄位的組合

const columns: GridColDef[] = [
  {
    field: 'fullName',
    valueGetter: (value, row) => {
      return `${row.firstName || ''} ${row.lastName || ''}`;
    },
  },
];

從複雜值衍生值

const columns: GridColDef[] = [
  {
    field: 'profit',
    valueGetter: (value, row) => {
      if (!row.gross || !row.costs) {
        return null;
      }
      return row.gross - row.costs;
    },
  },
];

valueGetter 傳回的值用於

篩選
排序
渲染（除非透過valueFormatter 或renderCell 進一步增強）

值格式器

值格式器允許您在顯示之前轉換值。常見的用例包括將 JavaScript Date 物件轉換為日期字串，或將 Number 轉換為格式化的數字（例如「1,000.50」）。

請注意，valueFormatter 傳回的值僅用於渲染目的。篩選和排序是基於原始值 (row[field]) 或valueGetter 傳回的值。

在以下示範中，valueGetter 用於將稅率（例如 0.2）轉換為小數值（例如 20），而 valueFormatter 用於將其顯示為百分比（例如 20%）。

渲染儲存格

預設情況下，Data Grid 將值渲染為儲存格中的字串。它按以下順序解析渲染的輸出

renderCell() => ReactElement
valueFormatter() => string
valueGetter() => string
row[field]

欄定義的 renderCell 方法與 valueFormatter 類似。但是，它進行了權衡，使其只能在儲存格中渲染，以換取允許傳回 React 節點（而不是字串）。

const columns: GridColDef[] = [
  {
    field: 'date',
    headerName: 'Year',
    renderCell: (params: GridRenderCellParams<any, Date>) => (
      <strong>
        {params.value.getFullYear()}
        <Button
          variant="contained"
          size="small"
          style={{ marginLeft: 16 }}
          tabIndex={params.hasFocus ? 0 : -1}
        >
          Open
        </Button>
      </strong>
    ),
  },
];

樣式化儲存格

您可以查看樣式化儲存格章節以取得更多資訊。

使儲存格可存取

儲存格內容不應在 Tab 鍵順序中，除非儲存格已聚焦。您可以查看Tab 鍵順序章節以取得更多資訊。

在渲染器內使用 Hook

renderCell 屬性是一個傳回 React 節點的函數，而不是 React 組件。

如果您想在渲染器內使用 React Hook，您應該將它們包裝在組件內。

// ❌ Not valid
const column = {
  // ...other properties,
  renderCell: () => {
    const [count, setCount] = React.useState(0);

    return (
      <Button onClick={() => setCount((prev) => prev + 1)}>{count} click(s)</Button>
    );
  },
};

// ✅ Valid
const CountButton = () => {
  const [count, setCount] = React.useState(0);

  return (
    <Button onClick={() => setCount((prev) => prev + 1)}>{count} click(s)</Button>
  );
};

const column = {
  // ...other properties,
  renderCell: () => <CountButton />,
};

展開儲存格渲染器

預設情況下，如果儲存格的內容不適合儲存格，Data Grid 會剪切儲存格的內容並渲染省略符號。作為一種解決方法，您可以建立一個儲存格渲染器，允許在 Data Grid 中查看儲存格的完整內容。

欄類型

為了方便欄的配置，預先定義了一些欄類型。預設情況下，欄被假定為保存字串，因此將應用預設的欄字串類型。因此，欄排序將使用字串比較器，並且欄內容將靠左對齊儲存格的左側。某些欄類型要求其值具有特定的類型。

以下是原生欄類型及其所需的值類型

欄類型	值類型
`'string'` (預設)	`字串`
`'number'`	`數字`
`'date'`	`Date() 物件`
`'dateTime'`	`Date() 物件`
`'boolean'`	`布林值`
`'singleSelect'`	`.valueOptions` 中的值
`'actions'`	不適用

轉換類型

預設方法（例如篩選和排序）假定值的類型將與 type 中指定的欄類型匹配。例如，type: 'dateTime' 的欄的值預期儲存為 Date() 物件。如果由於任何原因，您的資料類型不正確，您可以使用 valueGetter 將值解析為正確的類型。

{
  field: 'lastLogin',
  type: 'dateTime',
  valueGetter: (value) => value && new Date(value),
}

特殊屬性

若要使用大多數欄類型，您只需要在欄定義中定義 type 屬性。但是，某些類型需要設定其他屬性才能使其正常運作

單選

如果欄類型為 'singleSelect'，您還需要在相應的欄定義中設定 valueOptions 屬性。這些值是用於篩選和編輯的選項。

{
  field: 'country',
  type: 'singleSelect',
  valueOptions: ['United Kingdom', 'Spain', 'Brazil']
}

當對 valueOptions 使用物件值時，您需要為每個選項提供 value 和 label 屬性。但是，您可以分別使用 getOptionValue 和 getOptionLabel 自訂哪個屬性用作值和標籤。

// Without getOptionValue and getOptionLabel
{
  valueOptions: [
    { value: 'BR', label: 'Brazil' },
    { value: 'FR', label: 'France' }
  ]
}

// With getOptionValue and getOptionLabel
{
  getOptionValue: (value: any) => value.code,
  getOptionLabel: (value: any) => value.name,
  valueOptions: [
    { code: 'BR', name: 'Brazil' },
    { code: 'FR', name: 'France' }
  ]
}

動作

如果欄類型為 'actions'，您需要提供一個 getActions 函數，該函數傳回每個列可用的動作陣列（React 元素）。您可以在傳回的 React 元素上新增 showInMenu 屬性，以指示 Data Grid 將這些動作分組到列選單中。

{
  field: 'actions',
  type: 'actions',
  getActions: (params: GridRowParams) => [
    <GridActionsCellItem icon={...} onClick={...} label="Delete" />,
    <GridActionsCellItem icon={...} onClick={...} label="Print" showInMenu />,
  ]
}

預設情況下，選單中顯示的動作將在點擊時關閉選單。但在某些情況下，您可能希望在點擊動作後保持選單開啟。您可以透過將 closeMenuOnClick 屬性設定為 false 來實現此目的。

在以下範例中，「刪除」動作會開啟一個確認對話方塊，因此需要保持選單掛載

自訂欄類型

請參閱自訂欄頁面以取得文件和整合範例。

自動產生的列

某些功能（例如列分組或彙總）會建立自動產生的列。這些列也會呼叫 valueGetter、valueFormatter 和 renderCell 等函數，如果您沒有預料到，這可能會導致問題，因為 row 參數將是一個空物件，而 value 參數將是 undefined。如果我們以電影資料集為例，您可以使用 isAutogeneratedRow 偵測自動產生的列

{
  field: 'title',
  valueGetter: (value, row) => {
    if (isAutogeneratedRow(row)) {
      return '[this is an autogenerated row]';
    }
    return `title: ${value}`;
  },
}

選擇器

可見欄

這些選擇器不考慮隱藏的欄。

gridColumnPositionsSelector

取得每個可見欄的左側位置（以像素為單位），相對於第一欄的左側。

簽名

gridColumnPositionsSelector: (apiRef: GridApiRef) => number[]
// or
gridColumnPositionsSelector: (state: GridState, instanceId?: number) => number[]

範例

gridColumnPositionsSelector(apiRef)
// or
gridColumnPositionsSelector(state, apiRef.current.instanceId)

gridColumnVisibilityModelSelector

取得欄可見性模型，其中包含每個欄的可見性狀態。如果欄未在模型中註冊，則它是可見的。

簽名

gridColumnVisibilityModelSelector: (apiRef: GridApiRef) => GridColumnVisibilityModel
// or
gridColumnVisibilityModelSelector: (state: GridState, instanceId?: number) => GridColumnVisibilityModel

範例

gridColumnVisibilityModelSelector(apiRef)
// or
gridColumnVisibilityModelSelector(state, apiRef.current.instanceId)

gridColumnsTotalWidthSelector

取得所有可見欄的總寬度。

簽名

gridColumnsTotalWidthSelector: (apiRef: GridApiRef) => number
// or
gridColumnsTotalWidthSelector: (state: GridState, instanceId?: number) => number

範例

gridColumnsTotalWidthSelector(apiRef)
// or
gridColumnsTotalWidthSelector(state, apiRef.current.instanceId)

gridPinnedColumnsSelector

取得可見的釘選欄模型。

簽名

gridPinnedColumnsSelector: (state: GridState) => GridPinnedColumnFields

範例

const pinnedColumns = gridPinnedColumnsSelector(apiRef.current.state);

gridVisibleColumnDefinitionsSelector

以查找表形式取得可見欄（一個物件，其中包含欄位作為鍵，定義作為值）。

簽名

gridVisibleColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef[]
// or
gridVisibleColumnDefinitionsSelector: (state: GridState, instanceId?: number) => GridStateColDef[]

範例

gridVisibleColumnDefinitionsSelector(apiRef)
// or
gridVisibleColumnDefinitionsSelector(state, apiRef.current.instanceId)

gridVisibleColumnFieldsSelector

取得每個可見欄的欄位。

簽名

gridVisibleColumnFieldsSelector: (apiRef: GridApiRef) => string[]
// or
gridVisibleColumnFieldsSelector: (state: GridState, instanceId?: number) => string[]

範例

gridVisibleColumnFieldsSelector(apiRef)
// or
gridVisibleColumnFieldsSelector(state, apiRef.current.instanceId)

gridVisiblePinnedColumnDefinitionsSelector

取得可見的釘選欄。

簽名

gridVisiblePinnedColumnDefinitionsSelector: (apiRef: GridApiRef) => { left: GridStateColDef[]; right: GridStateColDef[] }
// or
gridVisiblePinnedColumnDefinitionsSelector: (state: GridState, instanceId?: number) => { left: GridStateColDef[]; right: GridStateColDef[] }

範例

gridVisiblePinnedColumnDefinitionsSelector(apiRef)
// or
gridVisiblePinnedColumnDefinitionsSelector(state, apiRef.current.instanceId)

已定義的欄

這些選擇器考慮所有已定義的欄，包括隱藏的欄。

gridColumnDefinitionsSelector

取得螢幕上渲染順序的欄定義陣列。

簽名

gridColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef[]
// or
gridColumnDefinitionsSelector: (state: GridState, instanceId?: number) => GridStateColDef[]

範例

gridColumnDefinitionsSelector(apiRef)
// or
gridColumnDefinitionsSelector(state, apiRef.current.instanceId)

gridColumnFieldsSelector

取得螢幕上渲染順序的欄位陣列。

簽名

gridColumnFieldsSelector: (apiRef: GridApiRef) => string[]
// or
gridColumnFieldsSelector: (state: GridState, instanceId?: number) => string[]

範例

gridColumnFieldsSelector(apiRef)
// or
gridColumnFieldsSelector(state, apiRef.current.instanceId)

gridColumnLookupSelector

以查找表形式取得欄（一個物件，其中包含欄位作為鍵，定義作為值）。

簽名

gridColumnLookupSelector: (apiRef: GridApiRef) => GridColumnLookup
// or
gridColumnLookupSelector: (state: GridState, instanceId?: number) => GridColumnLookup

範例

gridColumnLookupSelector(apiRef)
// or
gridColumnLookupSelector(state, apiRef.current.instanceId)

gridColumnsStateSelector

取得欄狀態

簽名

gridColumnsStateSelector: (state: GridState) => GridColumnsState

範例

const columnsState = gridColumnsStateSelector(apiRef.current.state);

gridFilterableColumnDefinitionsSelector

以陣列形式取得可篩選的欄。

簽名

gridFilterableColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef[]
// or
gridFilterableColumnDefinitionsSelector: (state: GridState, instanceId?: number) => GridStateColDef[]

範例

gridFilterableColumnDefinitionsSelector(apiRef)
// or
gridFilterableColumnDefinitionsSelector(state, apiRef.current.instanceId)

gridFilterableColumnLookupSelector

以查找表形式取得可篩選的欄（一個物件，其中包含欄位作為鍵，定義作為值）。

簽名

gridFilterableColumnLookupSelector: (apiRef: GridApiRef) => GridColumnLookup
// or
gridFilterableColumnLookupSelector: (state: GridState, instanceId?: number) => GridColumnLookup

範例

gridFilterableColumnLookupSelector(apiRef)
// or
gridFilterableColumnLookupSelector(state, apiRef.current.instanceId)

有關選擇器以及如何在專用頁面上使用它們的更多資訊。