1. 问题背景与传统方法的局限性
在 prestashop 1.7 中，许多开发者尝试通过直接修改 src/prestashopbundle/resources/views/admin/product/catalogpage/lists/products_table.html.twig 和 src/prestashopbundle/resources/views/admin/product/catalogpage/lists/list.html.twig 等 twig 模板文件来添加新的产品列。然而，这种方法通常无法成功显示数据（例如显示“n/a”），且存在以下主要问题：
- 数据源缺失： Twig 模板只负责渲染数据，它本身不负责查询和获取数据。如果后端控制器没有将 wholesale_price 字段传递给模板，那么模板无论如何修改也无法显示该数据。
- 核心文件修改： 直接修改 PrestaShop 核心文件是极力不推荐的做法。这会导致在系统升级时，您的修改会被覆盖，从而引发兼容性问题和维护困难。
- 非模块化： 这种方式不符合 PrestaShop 的模块化扩展原则，难以管理和部署。
为了安全、稳定且可持续地扩展 PrestaShop 后台功能，我们应该利用其提供的钩子（Hooks）机制。
2. PrestaShop 1.7 扩展机制：钩子（Hooks）
PrestaShop 的钩子机制允许模块在特定事件发生时执行自定义代码，从而在不修改核心文件的情况下扩展或修改系统行为。对于后台产品列表，actionAdminProductsListingFieldsModifier 钩子是一个非常强大的工具，它允许我们在产品列表的字段定义和数据查询阶段进行干预。
3. 核心解决方案：actionAdminProductsListingFieldsModifier 钩子
actionAdminProductsListingFieldsModifier 钩子在产品列表数据被查询和字段被渲染之前触发。通过实现这个钩子，我们可以：
- 向产品列表的 SQL 查询中添加新的 SELECT 字段。
- 定义新的列头及其属性（如标题、类型、是否可排序/过滤）。
3.1 步骤一：创建自定义 PrestaShop 模块
首先，我们需要创建一个新的 PrestaShop 模块。模块的结构通常如下：
mycustomwholesaleprice/ ├── mycustomwholesaleprice.php ├── config.xml ├── README.md ├── views/ │ └── templates/ │ └── admin/ │ └── configure.tpl
在 mycustomwholesaleprice.php 文件中，我们将定义模块的基本信息并注册钩子。
示例代码：mycustomwholesaleprice.php
<?php
if (!defined('_PS_VERSION_')) {
exit;
}
class MyCustomWholesalePrice extends Module
{
public function __construct()
{
$this->name = 'mycustomwholesaleprice';
$this->tab = 'front_office_features'; // 模块分类
$this->version = '1.0.0';
$this->author = 'Your Name';
$this->need_instance = 0;
$this->ps_versions_compliancy = [
'min' => '1.7.0.0',
'max' => _PS_VERSION_,
];
$this->bootstrap = true;
parent::__construct();
$this->displayName = $this->l('Custom Wholesale Price Column');
$this->description = $this->l('Adds a wholesale price column to the product listing in the back office.');
$this->confirmUninstall = $this->l('Are you sure you want to uninstall this module?');
}
public function install()
{
if (!parent::install() ||
!$this->registerHook('actionAdminProductsListingFieldsModifier')) {
return false;
}
return true;
}
public function uninstall()
{
if (!parent::uninstall() ||
!$this->unregisterHook('actionAdminProductsListingFieldsModifier')) {
return false;
}
return true;
}
/**
* Hook to modify the fields and SQL query for the product listing.
*
* @param array $params Contains 'fields', 'sql_select', 'sql_join', 'sql_where', 'sql_group_by', 'sql_order_by'
*/
public function hookActionAdminProductsListingFieldsModifier(array $params)
{
// 添加 wholesale_price 到 SELECT 语句
// 'ps' 是 ps_product_shop 表的常用别名
$params['sql_select'] .= ', ps.wholesale_price';
// 定义新的列
// 'wholesale_price' 键必须与 SQL_SELECT 中选择的字段名一致
$params['fields']['wholesale_price'] = [
'title' => $this->l('Wholesale price'), // 列标题，支持翻译
'align' => 'text-center', // 对齐方式
'type' => 'price', // 数据类型，PrestaShop 会自动格式化为货币
'filter_key' => 'ps!wholesale_price', // 用于过滤的键 (表别名!字段名)
'orderby_key' => 'ps!wholesale_price', // 用于排序的键
'search' => true, // 允许在此列进行搜索
'havingFilter' => true, // 允许在此列进行过滤
];
}
}
3.2 步骤二：实现 hookActionAdminProductsListingFieldsModifier 方法
在上面的 mycustomwholesaleprice.php 文件中，我们已经包含了 hookActionAdminProductsListingFieldsModifier 方法的实现。让我们详细解释其内部逻辑：
-
$params['sql_select'] .= ', ps.wholesale_price';
- 这一行代码是关键。它将 wholesale_price 字段添加到 PrestaShop 用于查询产品列表数据的 SQL SELECT 语句中。
- ps 是 PrestaShop 内部为 ps_product_shop 表（或在非多店铺模式下为 ps_product 表）定义的别名，wholesale_price 字段通常存储在这张表中。
- 通过这种方式，wholesale_price 数据就被成功地从数据库中检索出来，并传递给后续的渲染流程。
-
$params['fields']['wholesale_price'] = [...]
- 这部分代码定义了新的列在后台界面的显示方式。
- 'wholesale_price'： 这是新列的唯一标识符，必须与您在 sql_select 中添加的字段名完全匹配。
- 'title' => $this->l('Wholesale price')： 定义了列的显示标题。$this->l() 是 PrestaShop 的翻译函数，确保标题可以被翻译成不同语言。
- 'align' => 'text-center'： 设置列内容的对齐方式。
- 'type' => 'price'： 告诉 PrestaShop 这个字段是一个价格，系统会自动对其进行货币格式化显示。其他常见类型包括 text, bool, date 等。
- 'filter_key' => 'ps!wholesale_price'： 定义了在后台列表上方进行过滤时使用的键。格式为 表别名!字段名。
- 'orderby_key' => 'ps!wholesale_price'： 定义了在后台列表点击列头进行排序时使用的键。
- 'search' => true 和 'havingFilter' => true： 启用此列的搜索和过滤功能。
3.3 步骤三：安装并测试模块
- 将 mycustomwholesaleprice 文件夹上传到 PrestaShop 安装目录下的 modules/ 文件夹中。
- 登录 PrestaShop 后台，导航到 模块 > 模块管理器。
- 在模块列表中搜索“Custom Wholesale Price Column”或“mycustomwholesaleprice”。
- 点击“安装”按钮安装模块。
- 安装成功后，导航到 目录 > 产品。您应该能在产品列表的表格中看到新增的“批发价”列，并且数据会正确显示。您还可以尝试对该列进行排序和过滤。
4. 注意事项与最佳实践
- 模块化开发： 始终通过创建模块来扩展 PrestaShop 功能，避免直接修改核心文件，以确保系统的可升级性和稳定性。
- 翻译： 使用 $this->l() 函数来处理所有用户可见的字符串，以便您的模块支持多语言。
- 缓存清除： 在安装、卸载模块或修改模块代码后，务必清除 PrestaShop 的缓存（在后台：高级参数 > 性能，点击“清除缓存”）。
- 数据库字段： 确保 wholesale_price 字段确实存在于您的 PrestaShop 数据库的 ps_product_shop 表中。如果您的 PrestaShop 版本或配置中该字段名称不同，请相应调整 sql_select 和 filter_key/orderby_key 中的字段名。
- 兼容性： 虽然 actionAdminProductsListingFieldsModifier 钩子在 PrestaShop 1.7.x 版本中是稳定的，但不同版本之间可能存在细微差异。如果遇到问题，请查阅 PrestaShop 官方开发者文档。
- 错误排查： 如果新列未按预期显示，请检查 PrestaShop 的调试模式（在 config/defines.inc.php 中将 _PS_MODE_DEV_ 设置为 true），并查看服务器错误日志以获取更多信息。
- 参考实现： 如果需要更复杂的自定义，例如为批发价列添加自定义的链接或特定样式，您可能需要结合使用 Smarty 模板来渲染单元格内容。一个更完整的示例可以参考 GitHub 上的相关模块：https://www.php.cn/link/5dd0565bef8f4fb788527a171d688538。
5. 总结
通过利用 PrestaShop 1.7 的 actionAdminProductsListingFieldsModifier 钩子，我们可以以一种安全、高效且可维护的方式，在后台产品列表页面添加自定义列。这种模块化的方法不仅避免了直接修改核心文件带来的风险，还为开发者提供了极大的灵活性，以满足各种业务需求，同时确保了系统的长期稳定运行。掌握钩子的使用是成为一名合格 PrestaShop 开发者不可或缺的技能。
