企业官网建设流程全解析

• 企业应用
• 后端

本指南聚焦 Dolibarr ERP/CRM 模块开发中容易被忽略却至关重要的img/图片目录约定：$picto属性如何与模块内 PNG 图片文件对应、对象名@模块名语法如何被 Dolibarr 核心解析并渲染为界面图标。内容以官方模块模板的 img/README.md 为骨架，结合img_picto()核心函数源码逐一拆解命名规则、路径解析原理与实战配置示例，帮助你为自研模块配置正确、可复用的图标系统。

一、img 目录在模块模板中的定位

在 Dolibarr 的模块生成模板（ModuleBuilder）中，每个模块都包含一个标准的img/目录，其唯一职责就是存放该模块的图片资源（.png 文件）。在模板目录htdocs/modulebuilder/template/下可以看到完整的模块骨架，其中img/与class/、core/、langs/、sql/等目录平级，构成一个可独立分发、可直接 zip 打包部署的外部模块标准结构：

• class/：业务对象类（如myobject.class.php）
• core/modules/modMyModule.class.php：模块描述与激活类
• langs/：多语言文件
• sql/：建表与升级 SQL
• img/：模块与业务对象的 PNG 图标文件（即本文主题）

官方在 img/README.md 中用两句话给出了核心约定：

You can put here the .png files of your module

If the picto of your module is an image (property$pictohas been set to'mymodule.png@mymodule'), you can put into this directory a .png file calledobject_mymodule.png(16x16 or 32x32 pixels)

If the picto of an object is an image (property$pictoof the object.class.php has been set to'myobject.png@mymodule'), then you can put into this directory a .png file calledobject_myobject.png(16x16 or 32x32 pixels)

这段说明虽短，却完整覆盖了两种使用场景：模块级图标（显示在模块列表、菜单上）与业务对象级图标（显示在对象卡片、列表、标签页上）。下文逐一展开。

二、Picto 的三种取值方式：先从模块描述类看起

在模块激活类 modMyModule.class.php 中，$picto属性上的注释直接给出了三种合法取值方式：

// Name of image file used for this module. // If file is in theme/yourtheme/img directory under name object_pictovalue.png, use this->picto='pictovalue' // If file is in module/img directory under name object_pictovalue.png, use this->picto='pictovalue@module' // To use a supported fa-xxx css style of font awesome, use this->picto='xxx' $this->picto = 'generic';

即一个模块（或业务对象）的图标可以来自三种渠道：

模板默认值'generic'走的是主题目录，指向主题下的通用占位图标；而只要你想让模块自带品牌化图标，就必须使用第二种形式，也就是@语法，并把 PNG 文件放进img/目录。

同样，业务对象类 myobject.class.php 中也有一致的注释：

/** * @var string String with name of icon for myobject. Must be a 'fa-xxx' fontawesome code * (or 'fa-xxx_fa_color_size') or 'myobject@mymodule' if picto is file 'img/object_myobject.png'. */ public $picto = 'fa-file';

模板默认给对象使用的是 FontAwesome 的fa-file，注释明确说明：如果改用图片文件，就写成'myobject@mymodule'，文件则放在img/object_myobject.png。

三、img 目录的命名约定：object_ 前缀与尺寸要求

结合 img/README.md 的内容，规则可以提炼为一张对照表：

三个关键点值得强调：

1. object_前缀是硬性要求。@前的文件名在拼装最终 URL 时会被直接用作img/下的实际文件名，因此$picto = 'mymodule.png@mymodule'对应的真实文件必须命名为object_mymodule.png而不是mymodule.png。同理，对象图片是object_myobject.png。
2. 尺寸建议 16x16 或 32x32 像素。Dolibarr 界面中图标以小尺寸出现于菜单、列表、标签页与模块管理页，过大或过小的图都会导致界面显示失衡。建议制作为正方形 PNG，透明背景更佳。
3. @后面的部分必须是模块目录名（本例为mymodule），它决定了 Dolibarr 去哪里找这张图——即该模块在 htdocs（或 custom）下的目录名。

四、源码原理：img_picto() 如何解析 @ 语法与拼接路径

要真正理解命名规则，必须看核心渲染函数img_picto()，它定义于 html.lib.php。模块模板中菜单项正是通过img_picto('', $this->picto, ...)来生成图标前缀（见 modMyModule.class.php 的 topmenu 定义），所以$picto的取值最终都会被送到这个函数。

img_picto()的解析流程可以归纳为以下几个关键步骤：

**第一步：默认路径预设。**函数默认将图片路径指向DOL_URL_ROOT/theme/$conf->theme/img/（L1318-L1321），这解释了第一种取值方式（不带@）为何会去主题目录找图。

**第二步：Font Awesome 分流。**如果$picto以fa-或fontawesome_开头，则直接渲染<span>字体图标，不涉及任何图片文件（L1357-L1402）。不带/、.、@的普通值也会被转换为fa-xxx输出（L1404 起的分支）。注意这里会先剥离object_前缀（L1342），用于把object_xxx归一化为 FontAwesome key。

**第三步：@ 语法拆分。**关键正则位于 L1687-L1690：

if (preg_match('/^([^@]+)@([^@]+)$/i', $picto, $regs)) { $picto = $regs[1]; // 图片文件名，如 myobject.png $path = $regs[2]; // 模块目录名，如 myobject }

即'myobject.png@mymodule'被拆成图片名myobject.png与路径mymodule两部分。

**第四步：扩展名补全。**如果文件名没有.png/.gif/.svg扩展名，会自动补上.png（L1693-L1695）。这就是为什么$picto既可以写'myobject.png@mymodule'也可以写'myobject@mymodule'，两种写法最终都会指向.png文件。

**第五步：备用目录查找与最终拼接。**最终 URL 在 L1710 完成：

$fullpathpicto = $url . '/' . $path . '/img/' . $picto;

代入上面的例子即…/mymodule/img/myobject.png。在此之前，函数还会遍历$conf->file->dol_document_root中的备用根目录（如custom目录），优先使用能找到物理文件的根（L1697-L1707）——这意味着把模块放进htdocs/custom/时，img/下的图标同样能被正确解析。若调用时传入$srconly=1，函数则直接返回图片 URL 字符串而不输出<img>标签（L1713-L1715），可用于需要在 PHP 中单独取得图标地址的场景。

五、实战配置：为你的模块与对象启用图片图标

以下三步即可为模块配置完整的图片图标体系。

**第 1 步：准备图片文件。**制作两张 32x32 的透明 PNG：object_mymodule.png（模块图标）与object_myobject.png（业务对象图标），放入模块的img/目录（即htdocs/modulebuilder/template/img/同级位置，若为自定义模块则在htdocs/custom/你的模块/img/下）。

**第 2 步：修改模块描述类。**在 modMyModule.class.php 中把默认的'generic'改为@形式：

$this->picto = 'mymodule.png@mymodule';

这一属性会同时作用于模块列表、顶栏菜单与左侧菜单（菜单定义中的'prefix' => img_picto('', $this->picto, ...)会自动复用该值）。此外，若希望 Dolistore 风格市场展示方形 Logo，模板还提供了editor_squarred_logo属性，注释同样要求"图片文件名后跟@modulename"形式，例如'myimage.png@mymodule'（见 modMyModule.class.php）。

**第 3 步：修改业务对象类。**在 myobject.class.php 中把对象的默认'fa-file'替换为：

public $picto = 'myobject.png@mymodule';

保存后重新进入模块管理页停用再启用模块，Dolibarr 会重新读取模块描述并刷新菜单与权限缓存，随后在对象卡片、列表行首和新增标签页（tab）上即可看到自定义图片图标。

六、排查要点与最佳实践

结合源码可以总结出几个常见坑：

• 文件名必须带object_前缀：$picto中@前的名字与img/下实际文件名必须一致，且实际文件要以object_开头。例如$picto='myobject.png@mymodule'时文件必须是object_myobject.png，否则 L1710 拼出的路径会 404。
• @后必须是模块目录名：写错模块名会回退到错误的img/路径，界面显示破图。
• 不用写扩展名也可以：'myobject@mymodule'会被自动补全为.png，但显式写全扩展名更清晰。
• 不要与非 @ 语法混淆：$picto='myobject'（不带@）会被当成 Font Awesome 图标渲染为fa-myobject，而不是去模块img/找图——这是最常见的误配置。
• 尺寸与格式：坚持 16x16 或 32x32 的正方形 PNG；若使用.svg矢量图也可被 L1693 的扩展名判断识别。
• 多实体（Multicompany）环境：备用目录遍历逻辑（L1697-L1707）决定了custom目录下的模块图片同样可用，但应避免在main根目录之外重复放置同名文件造成路径歧义。

七、延伸阅读

• 模块图片目录约定原文：img/README.md
• img_picto()完整实现与 @ 语法解析：html.lib.php
• 模块描述类中$picto、editor_squarred_logo的声明与注释：modMyModule.class.php
• 业务对象类中对象级$picto的声明：myobject.class.php
• 模块模板整体结构与安装部署说明：template/README.md

• 企业应用
• 后端