0 追蹤者

類別 yii\grid\DataColumn

所有類別 | 屬性 | 方法
繼承yii\grid\DataColumn » yii\grid\Column » yii\base\BaseObject
實作yii\base\Configurable
自版本起可用2.0
原始碼 https://github.com/yiisoft/yii2/blob/master/framework/grid/DataColumn.php

DataColumn 是 yii\grid\GridView 小工具的預設欄位類型。

它用於顯示資料欄位，並允許對它們進行排序和篩選。

一個簡單的資料欄位定義指的是 GridView 資料提供者的資料模型中的一個屬性。屬性的名稱由 $attribute 指定。

通過設定 $value 和 $label，可以自訂標題和儲存格內容。

資料欄位區分資料儲存格值和資料儲存格內容。儲存格值是一個未格式化的值，可用於計算，而實際的儲存格內容是該值的$format版本，可能包含 HTML 標記。

有關 DataColumn 的更多詳細資訊和使用方法，請參閱關於資料小工具的指南文章。

公開屬性

隱藏繼承的屬性

屬性 類型 描述 定義於
$attribute 字串 與此欄位關聯的屬性名稱。 yii\grid\DataColumn
$content 可呼叫 這是一個可呼叫的函式，將用於產生每個儲存格的內容。 yii\grid\Column
$contentOptions 陣列|Closure 資料儲存格標籤的 HTML 屬性。 yii\grid\Column
$enableSorting 布林值 是否允許依此欄位排序。 yii\grid\DataColumn
$encodeLabel 布林值 標題標籤是否應進行 HTML 編碼。 yii\grid\DataColumn
$filter 字串|陣列|null|false 代表用於此資料欄位的篩選輸入（例如文字欄位、下拉式選單）的 HTML 代碼。 yii\grid\DataColumn
$filterAttribute 字串|null 與此欄位關聯的 yii\grid\GridView::$filterModel 的屬性名稱。 yii\grid\DataColumn
$filterInputOptions 陣列 篩選輸入欄位的 HTML 屬性。 yii\grid\DataColumn
$filterOptions 陣列 篩選儲存格標籤的 HTML 屬性。 yii\grid\Column
$footer 字串 頁腳儲存格內容。 yii\grid\Column
$footerOptions 陣列 頁腳儲存格標籤的 HTML 屬性。 yii\grid\Column
$format 字串|陣列|Closure 應該以哪種格式顯示每個資料模型的值（例如 "raw"、"text"、"html"、['date', 'php:Y-m-d']）。 yii\grid\DataColumn
$grid yii\grid\GridView 擁有此欄位的網格視圖物件。 yii\grid\Column
$header 字串|null 標題儲存格內容。 yii\grid\Column
$headerOptions 陣列 標題儲存格標籤的 HTML 屬性。 yii\grid\Column
$label 字串|null 要顯示在標題儲存格中的標籤，以及當此欄位啟用排序時，也將用作排序連結標籤。 yii\grid\DataColumn
$options 陣列 欄位群組標籤的 HTML 屬性。 yii\grid\Column
$sortLinkOptions 陣列 當此欄位啟用排序時，由 yii\data\Sort::link() 產生的標題儲存格中連結標籤的 HTML 屬性。 yii\grid\DataColumn
$value 字串|Closure|null 用於決定在目前欄位中顯示值的匿名函式或字串。 yii\grid\DataColumn
$visible 布林值 此欄位是否可見。 yii\grid\Column

公開方法

隱藏繼承的方法

方法 描述 定義於
__call() 呼叫未作為類別方法的具名方法。 yii\base\BaseObject
__construct() 建構子。 yii\base\BaseObject
__get() 傳回物件屬性的值。 yii\base\BaseObject
__isset() 檢查屬性是否已設定，亦即已定義且非空值。 yii\base\BaseObject
__set() 設定物件屬性的值。 yii\base\BaseObject
__unset() 將物件屬性設為空值。 yii\base\BaseObject
canGetProperty() 傳回值，指出屬性是否可讀取。 yii\base\BaseObject
canSetProperty() 傳回值，指出屬性是否可設定。 yii\base\BaseObject
className() 傳回此類別的完整命名空間名稱。 yii\base\BaseObject
getDataCellValue() 傳回資料儲存格的值。 yii\grid\DataColumn
hasMethod() 傳回值，指出是否已定義方法。 yii\base\BaseObject
hasProperty() 傳回值，指出是否已定義屬性。 yii\base\BaseObject
init() 初始化物件。 yii\grid\DataColumn
renderDataCell() 渲染資料儲存格。 yii\grid\Column
renderFilterCell() 渲染篩選器儲存格。 yii\grid\Column
renderFooterCell() 渲染頁腳儲存格。 yii\grid\Column
renderHeaderCell() 渲染標頭儲存格。 yii\grid\Column

受保護的方法

隱藏繼承的方法

方法 描述 定義於
getHeaderCellLabel() 傳回標頭儲存格標籤。 yii\grid\DataColumn
renderDataCellContent() 渲染資料儲存格內容。 yii\grid\DataColumn
renderFilterCellContent() 渲染篩選器儲存格內容。 yii\grid\DataColumn
renderFooterCellContent() 渲染頁腳儲存格內容。 yii\grid\Column
renderHeaderCellContent() 渲染標頭儲存格內容。 yii\grid\DataColumn

屬性詳細資訊

隱藏繼承的屬性

$attribute 公開屬性

與此欄位關聯的屬性名稱。當未指定 $content 或 $value 時，將從每個資料模型中擷取指定屬性的值並顯示。

此外，如果未指定 $label，則將顯示與屬性關聯的標籤。

public string $attribute = null
$enableSorting 公開屬性

是否允許依此欄位排序。如果為 true 且在 yii\grid\GridView::$dataProvider 的排序定義中找到 $attribute，則此欄位的標頭儲存格將包含一個連結，點擊時可能會觸發排序。

public boolean $enableSorting = true
$encodeLabel 公開屬性 (自版本 2.0.1 起可用)

標題標籤是否應進行 HTML 編碼。

另請參閱 $label。

public boolean $encodeLabel = true
$filter 公開屬性

代表此資料欄位所用篩選器輸入 (例如文字欄位、下拉式清單) 的 HTML 程式碼。僅當設定 yii\grid\GridView::$filterModel 時，此屬性才有效。

  • 如果未設定此屬性，則會產生一個文字欄位作為篩選器輸入，其屬性使用 $filterInputOptions 定義。請參閱 yii\helpers\BaseHtml::activeInput()，以瞭解如何產生作用中輸入標籤的詳細資訊。
  • 如果此屬性是陣列，則會產生一個下拉式清單，該清單使用此屬性值作為清單選項。
  • 如果您不希望此資料欄位有篩選器，請將此值設定為 false。
public string|array|null|false $filter = null
$filterAttribute 公開屬性 (自版本 2.0.41 起可用)

與此欄位關聯的 yii\grid\GridView::$filterModel 的屬性名稱。如果未設定，則會與 $attribute 具有相同的值。

public string|null $filterAttribute = null
$filterInputOptions 公開屬性

篩選器輸入欄位的 HTML 屬性。此屬性與 $filter 屬性結合使用。當 $filter 未設定或為陣列時，此屬性將用於渲染產生的篩選器輸入欄位的 HTML 屬性。

預設值中的空 id 可確保 id 不會從模型屬性中取得，從而提供更好的效能。

另請參閱 yii\helpers\Html::renderTagAttributes()，以瞭解如何渲染屬性的詳細資訊。

public array $filterInputOptions = [
    'class' => 'form-control',
    'id' => null,
]
$format 公開屬性

每個資料模型的值應以哪種格式顯示 (例如 "raw"、"text"、"html"、['date', 'php:Y-m-d'])。支援的格式由 formatter 決定，該格式由 yii\grid\GridView 使用。預設格式為 "text"，當 yii\i18n\Formatter 用作 GridView 的 formatter 時，它會將值格式化為 HTML 編碼的純文字。

另請參閱 yii\i18n\Formatter::format()。

public string|array|Closure $format = 'text'
$label 公開屬性

要顯示在 標頭儲存格 中的標籤，以及在啟用此欄位排序時用作排序連結標籤的標籤。如果未設定且 GridView 資料提供者提供的模型是 yii\db\ActiveRecord 的實例，則標籤將使用 yii\db\ActiveRecord::getAttributeLabel() 決定。否則，將使用 yii\helpers\Inflector::camel2words() 來取得標籤。

public string|null $label = null
$sortLinkOptions 公開屬性

當此欄位啟用排序時，由 yii\data\Sort::link() 產生的標題儲存格中連結標籤的 HTML 屬性。

另請參閱 yii\helpers\Html::renderTagAttributes()，以瞭解如何渲染屬性的詳細資訊。

public array $sortLinkOptions = []
$value 公開屬性

用於決定在目前欄位中顯示值的匿名函式或字串。

如果這是匿名函式，則會針對每一列呼叫它，且傳回值將用作每個資料模型要顯示的值。此函式的簽名應為：function ($model, $key, $index, $column)。其中 $model、$key 和 $index 指的是目前正在渲染的列的模型、鍵和索引，而 $column 是對 yii\grid\DataColumn 物件的參考。

您也可以將此屬性設定為代表要在此欄位中顯示的屬性名稱的字串。當要顯示的屬性與用於排序和篩選的 $attribute 不同時，可以使用此選項。

如果未設定此項，則將使用 $model[$attribute] 來取得值，其中 $attribute 是 $attribute 的值。

public string|Closure|null $value = null

方法詳細資訊

隱藏繼承的方法

__call() 公開方法

定義於： yii\base\BaseObject::__call()

呼叫未作為類別方法的具名方法。

請勿直接呼叫此方法，因為它是 PHP 魔術方法，當呼叫未知方法時，將會隱含地呼叫它。

public mixed __call ( $name, $params )
$name 字串

方法名稱
$params 陣列

方法參數
return mixed

方法傳回值
throws yii\base\UnknownMethodException

當呼叫未知方法時

 

                public function __call($name, $params)
{
    throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}
__construct() 公開方法

定義於： yii\base\BaseObject::__construct()

建構子。

預設實作執行兩件事

  • 使用給定的組態 $config 初始化物件。
  • 呼叫 init()。

如果子類別中覆寫了此方法，建議

  • 建構子的最後一個參數是組態陣列，例如此處的 $config。
  • 在建構子結尾呼叫父類別實作。
public void __construct ( $config = [] )
$config 陣列

將用於初始化物件屬性的名稱-值配對

 

                public function __construct($config = [])
{
    if (!empty($config)) {
        Yii::configure($this, $config);
    }
    $this->init();
}
__get() 公開方法

定義於： yii\base\BaseObject::__get()

傳回物件屬性的值。

請勿直接呼叫此方法，因為它是 PHP 魔術方法，當執行 $value = $object->property; 時，將會隱含地呼叫它。

另請參閱 __set()。

public mixed __get ( $name )
$name 字串

屬性名稱
return mixed

屬性值
throws yii\base\UnknownPropertyException

如果未定義屬性
throws yii\base\InvalidCallException

如果屬性為唯寫

 

                public function __get($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        return $this->$getter();
    } elseif (method_exists($this, 'set' . $name)) {
        throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
    }
    throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
}
__isset() 公開方法

定義於： yii\base\BaseObject::__isset()

檢查屬性是否已設定，亦即已定義且非空值。

請勿直接呼叫此方法，因為它是 PHP 魔術方法，當執行 isset($object->property) 時，將會隱含地呼叫它。

請注意，如果未定義屬性，將傳回 false。

另請參閱 https://php.dev.org.tw/manual/en/function.isset.php。

public boolean __isset ( $name )
$name 字串

屬性名稱或事件名稱
return 布林值

具名屬性是否已設定 (非空值)。

 

                public function __isset($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        return $this->$getter() !== null;
    }
    return false;
}
__set() 公開方法

定義於： yii\base\BaseObject::__set()

設定物件屬性的值。

請勿直接呼叫此方法，因為它是 PHP 魔術方法，當執行 $object->property = $value; 時，將會隱含地呼叫它。

另請參閱 __get()。

public void __set ( $name, $value )
$name 字串

屬性名稱或事件名稱
$value mixed

屬性值
throws yii\base\UnknownPropertyException

如果未定義屬性
throws yii\base\InvalidCallException

如果屬性為唯讀

 

                public function __set($name, $value)
{
    $setter = 'set' . $name;
    if (method_exists($this, $setter)) {
        $this->$setter($value);
    } elseif (method_exists($this, 'get' . $name)) {
        throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
    } else {
        throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
    }
}
__unset() 公開方法

定義於： yii\base\BaseObject::__unset()

將物件屬性設為空值。

請勿直接呼叫此方法，因為它是 PHP 魔術方法，當執行 unset($object->property) 時，將會隱含地呼叫它。

請注意，如果未定義屬性，此方法將不會執行任何動作。如果屬性為唯讀，則會擲回例外狀況。

另請參閱 https://php.dev.org.tw/manual/en/function.unset.php。

public void __unset ( $name )
$name 字串

屬性名稱
throws yii\base\InvalidCallException

如果屬性為唯讀。

 

                public function __unset($name)
{
    $setter = 'set' . $name;
    if (method_exists($this, $setter)) {
        $this->$setter(null);
    } elseif (method_exists($this, 'get' . $name)) {
        throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
    }
}
canGetProperty() 公開方法

定義於： yii\base\BaseObject::canGetProperty()

傳回值，指出屬性是否可讀取。

如果符合以下條件，則屬性為可讀取：

  • 類別具有與指定名稱關聯的 getter 方法 (在此情況下，屬性名稱不區分大小寫)；
  • 類別具有具有指定名稱的成員變數 (當 $checkVars 為 true 時)；

另請參閱 canSetProperty()。

public boolean canGetProperty ( $name, $checkVars = true )
$name 字串

屬性名稱
$checkVars 布林值

是否將成員變數視為屬性
return 布林值

屬性是否可讀取

 

                public function canGetProperty($name, $checkVars = true)
{
    return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
}
canSetProperty() 公開方法

定義於： yii\base\BaseObject::canSetProperty()

傳回值，指出屬性是否可設定。

如果符合以下條件，則屬性為可寫入：

  • 類別具有與指定名稱關聯的 setter 方法 (在此情況下，屬性名稱不區分大小寫)；
  • 類別具有具有指定名稱的成員變數 (當 $checkVars 為 true 時)；

另請參閱 canGetProperty()。

public boolean canSetProperty ( $name, $checkVars = true )
$name 字串

屬性名稱
$checkVars 布林值

是否將成員變數視為屬性
return 布林值

屬性是否可寫入

 

                public function canSetProperty($name, $checkVars = true)
{
    return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
}
className() 公開靜態方法
自 2.0.14 版起已棄用。在 PHP >=5.5 上，請改用 ::class。

定義於： yii\base\BaseObject::className()

傳回此類別的完整命名空間名稱。

public static string className ( )
return 字串

此類別的完整命名空間名稱。

 

                public static function className()
{
    return get_called_class();
}
getDataCellValue() 公開方法

傳回資料儲存格的值。

public string getDataCellValue ( $model, $key, $index )
$model mixed

資料模型
$key mixed

與資料模型關聯的鍵
$index integer

dataProvider 所傳回的模型陣列中，資料模型的從零開始的索引 yii\grid\GridView::$dataProvider。
return 字串

資料儲存格值

 

                public function getDataCellValue($model, $key, $index)
{
    if ($this->value !== null) {
        if (is_string($this->value)) {
            return ArrayHelper::getValue($model, $this->value);
        }
        return call_user_func($this->value, $model, $key, $index, $this);
    } elseif ($this->attribute !== null) {
        return ArrayHelper::getValue($model, $this->attribute);
    }
    return null;
}
getHeaderCellLabel() 受保護的方法 (自版本 2.0.8 起可用)

傳回標頭儲存格標籤。

可以覆寫此方法以自訂標頭儲存格的標籤。

protected string getHeaderCellLabel ( )
return 字串

標籤

 

                protected function getHeaderCellLabel()
{
    $provider = $this->grid->dataProvider;
    if ($this->label === null) {
        if ($this->attribute === null) {
            $label = '';
        } elseif ($provider instanceof ActiveDataProvider && $provider->query instanceof ActiveQueryInterface) {
            /* @var $modelClass Model */
            $modelClass = $provider->query->modelClass;
            $model = $modelClass::instance();
            $label = $model->getAttributeLabel($this->attribute);
        } elseif ($provider instanceof ArrayDataProvider && $provider->modelClass !== null) {
            /* @var $modelClass Model */
            $modelClass = $provider->modelClass;
            $model = $modelClass::instance();
            $label = $model->getAttributeLabel($this->attribute);
        } elseif ($this->grid->filterModel !== null && $this->grid->filterModel instanceof Model) {
            $label = $this->grid->filterModel->getAttributeLabel($this->filterAttribute);
        } else {
            $models = $provider->getModels();
            if (($model = reset($models)) instanceof Model) {
                /* @var $model Model */
                $label = $model->getAttributeLabel($this->attribute);
            } else {
                $label = Inflector::camel2words($this->attribute);
            }
        }
    } else {
        $label = $this->label;
    }
    return $label;
}
hasMethod() 公開方法

定義於： yii\base\BaseObject::hasMethod()

傳回值，指出是否已定義方法。

預設實作是對 php 函數 method_exists() 的呼叫。當您實作 php 魔術方法 __call() 時，可以覆寫此方法。

public boolean hasMethod ( $name )
$name 字串

方法名稱
return 布林值

方法是否已定義

 

                public function hasMethod($name)
{
    return method_exists($this, $name);
}
hasProperty() public method

定義於： yii\base\BaseObject::hasProperty()

傳回值，指出是否已定義屬性。

如果屬性被定義為

  • 類別具有與指定名稱相關聯的 getter 或 setter 方法（在這種情況下，屬性名稱不區分大小寫）；
  • 類別具有具有指定名稱的成員變數 (當 $checkVars 為 true 時)；

參見

public boolean hasProperty ( $name, $checkVars = true )
$name 字串

屬性名稱
$checkVars 布林值

是否將成員變數視為屬性
return 布林值

屬性是否被定義

 

                public function hasProperty($name, $checkVars = true)
{
    return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
}
init() public method

初始化物件。

在物件使用給定的配置初始化之後，此方法會在建構函式的結尾被調用。

public void init ( )

                public function init()
{
    parent::init();
    if ($this->filterAttribute === null) {
        $this->filterAttribute = $this->attribute;
    }
}
renderDataCell() public method

定義於： yii\grid\Column::renderDataCell()

渲染資料儲存格。

public string renderDataCell ( $model, $key, $index )
$model mixed

正在呈現的資料模型
$key mixed

與資料模型關聯的鍵
$index integer

資料項目在 yii\grid\GridView::$dataProvider 傳回的項目陣列中的從零開始的索引。
return 字串

呈現結果

 

                public function renderDataCell($model, $key, $index)
{
    if ($this->contentOptions instanceof Closure) {
        $options = call_user_func($this->contentOptions, $model, $key, $index, $this);
    } else {
        $options = $this->contentOptions;
    }
    return Html::tag('td', $this->renderDataCellContent($model, $key, $index), $options);
}
renderDataCellContent() protected method

渲染資料儲存格內容。

protected string renderDataCellContent ( $model, $key, $index )
$model mixed

資料模型
$key mixed

與資料模型關聯的鍵
$index integer

dataProvider 所傳回的模型陣列中，資料模型的從零開始的索引 yii\grid\GridView::$dataProvider。
return 字串

呈現結果

 

                protected function renderDataCellContent($model, $key, $index)
{
    if ($this->content === null) {
        return $this->grid->formatter->format($this->getDataCellValue($model, $key, $index), $this->format);
    }
    return parent::renderDataCellContent($model, $key, $index);
}
renderFilterCell() public method

定義於： yii\grid\Column::renderFilterCell()

渲染篩選器儲存格。

public void renderFilterCell ( )

                public function renderFilterCell()
{
    return Html::tag('td', $this->renderFilterCellContent(), $this->filterOptions);
}
renderFilterCellContent() protected method

渲染篩選器儲存格內容。

預設實作僅呈現一個空格。此方法可以被覆寫以自訂篩選器儲存格（如果有的話）的呈現方式。

protected string renderFilterCellContent ( )
return 字串

呈現結果

 

                protected function renderFilterCellContent()
{
    if (is_string($this->filter)) {
        return $this->filter;
    }
    $model = $this->grid->filterModel;
    if ($this->filter !== false && $model instanceof Model && $this->filterAttribute !== null && $model->isAttributeActive($this->filterAttribute)) {
        if ($model->hasErrors($this->filterAttribute)) {
            Html::addCssClass($this->filterOptions, 'has-error');
            $error = ' ' . Html::error($model, $this->filterAttribute, $this->grid->filterErrorOptions);
        } else {
            $error = '';
        }
        if (is_array($this->filter)) {
            $options = array_merge(['prompt' => '', 'strict' => true], $this->filterInputOptions);
            return Html::activeDropDownList($model, $this->filterAttribute, $this->filter, $options) . $error;
        } elseif ($this->format === 'boolean') {
            $options = array_merge(['prompt' => '', 'strict' => true], $this->filterInputOptions);
            return Html::activeDropDownList($model, $this->filterAttribute, [
                1 => $this->grid->formatter->booleanFormat[1],
                0 => $this->grid->formatter->booleanFormat[0],
            ], $options) . $error;
        }
        $options = array_merge(['maxlength' => true], $this->filterInputOptions);
        return Html::activeTextInput($model, $this->filterAttribute, $options) . $error;
    }
    return parent::renderFilterCellContent();
}
renderFooterCell() public method

定義於： yii\grid\Column::renderFooterCell()

渲染頁腳儲存格。

public void renderFooterCell ( )

                public function renderFooterCell()
{
    return Html::tag('td', $this->renderFooterCellContent(), $this->footerOptions);
}
renderFooterCellContent() protected method

定義於： yii\grid\Column::renderFooterCellContent()

渲染頁腳儲存格內容。

預設實作僅呈現 $footer。此方法可以被覆寫以自訂頁尾儲存格的呈現方式。

protected string renderFooterCellContent ( )
return 字串

呈現結果

 

                protected function renderFooterCellContent()
{
    return $this->footer !== null && trim($this->footer) !== '' ? $this->footer : $this->grid->emptyCell;
}
renderHeaderCell() public method

定義於： yii\grid\Column::renderHeaderCell()

渲染標頭儲存格。

public void renderHeaderCell ( )

                public function renderHeaderCell()
{
    return Html::tag('th', $this->renderHeaderCellContent(), $this->headerOptions);
}
renderHeaderCellContent() protected method

渲染標頭儲存格內容。

預設實作僅呈現 $header。此方法可以被覆寫以自訂標頭儲存格的呈現方式。

protected string renderHeaderCellContent ( )
return 字串

呈現結果

 

                protected function renderHeaderCellContent()
{
    if ($this->header !== null || $this->label === null && $this->attribute === null) {
        return parent::renderHeaderCellContent();
    }
    $label = $this->getHeaderCellLabel();
    if ($this->encodeLabel) {
        $label = Html::encode($label);
    }
    if (
        $this->attribute !== null && $this->enableSorting &&
        ($sort = $this->grid->dataProvider->getSort()) !== false && $sort->hasAttribute($this->attribute)
    ) {
        return $sort->link($this->attribute, array_merge($this->sortLinkOptions, ['label' => $label]));
    }
    return $label;
}