企业应用后端【免费下载链接】dolibarrDolibarr ERP CRM is a modern software package to manage your company or foundations activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). its an open source Web application (written in PHP) designed for businesses of any sizes, foundations and freelancers.项目地址https://gitcode.com/gh_mirrors/do/dolibarr点击查看免费下载本指南聚焦 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.phpcore/modules/modMyModule.class.php模块描述与激活类langs/多语言文件sql/建表与升级 SQLimg/模块与业务对象的 PNG 图标文件即本文主题官方在 img/README.md 中用两句话给出了核心约定You can put here the .png files of your moduleIf the picto of your module is an image (property$pictohas been set tomymodule.pngmymodule), 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 tomyobject.pngmymodule), 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-pictopictovalue // If file is in module/img directory under name object_pictovalue.png, use this-pictopictovaluemodule // To use a supported fa-xxx css style of font awesome, use this-pictoxxx $this-picto generic;即一个模块或业务对象的图标可以来自三种渠道取值形式图片实际位置示例pictovalue主题目录theme/当前主题/img/object_pictovalue.pnggenericpictovaluemodule模块目录模块路径/img/object_pictovalue.pngmymodule.pngmymodulefa-xxx风格无需图片文件由 Font Awesome 字体渲染fa-file模板默认值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 myobjectmymodule if picto is file img/object_myobject.png. */ public $picto fa-file;模板默认给对象使用的是 FontAwesome 的fa-file注释明确说明如果改用图片文件就写成myobjectmymodule文件则放在img/object_myobject.png。三、img 目录的命名约定object_ 前缀与尺寸要求结合 img/README.md 的内容规则可以提炼为一张对照表使用场景$picto属性取值放入 img/ 的文件名推荐尺寸模块级图标mymodule.pngmymoduleobject_mymodule.png16x16 或 32x32对象级图标myobject.pngmymoduleobject_myobject.png16x16 或 32x32三个关键点值得强调object_前缀是硬性要求。前的文件名在拼装最终 URL 时会被直接用作img/下的实际文件名因此$picto mymodule.pngmymodule对应的真实文件必须命名为object_mymodule.png而不是mymodule.png。同理对象图片是object_myobject.png。尺寸建议 16x16 或 32x32 像素。Dolibarr 界面中图标以小尺寸出现于菜单、列表、标签页与模块管理页过大或过小的图都会导致界面显示失衡。建议制作为正方形 PNG透明背景更佳。后面的部分必须是模块目录名本例为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-L1690if (preg_match(/^([^])([^])$/i, $picto, $regs)) { $picto $regs[1]; // 图片文件名如 myobject.png $path $regs[2]; // 模块目录名如 myobject }即myobject.pngmymodule被拆成图片名myobject.png与路径mymodule两部分。**第四步扩展名补全。**如果文件名没有.png/.gif/.svg扩展名会自动补上.pngL1693-L1695。这就是为什么$picto既可以写myobject.pngmymodule也可以写myobjectmymodule两种写法最终都会指向.png文件。**第五步备用目录查找与最终拼接。**最终 URL 在 L1710 完成$fullpathpicto $url . / . $path . /img/ . $picto;代入上面的例子即…/mymodule/img/myobject.png。在此之前函数还会遍历$conf-file-dol_document_root中的备用根目录如custom目录优先使用能找到物理文件的根L1697-L1707——这意味着把模块放进htdocs/custom/时img/下的图标同样能被正确解析。若调用时传入$srconly1函数则直接返回图片 URL 字符串而不输出img标签L1713-L1715可用于需要在 PHP 中单独取得图标地址的场景。五、实战配置为你的模块与对象启用图片图标以下三步即可为模块配置完整的图片图标体系。**第 1 步准备图片文件。**制作两张 32x32 的透明 PNGobject_mymodule.png模块图标与object_myobject.png业务对象图标放入模块的img/目录即htdocs/modulebuilder/template/img/同级位置若为自定义模块则在htdocs/custom/你的模块/img/下。**第 2 步修改模块描述类。**在 modMyModule.class.php 中把默认的generic改为形式$this-picto mymodule.pngmymodule;这一属性会同时作用于模块列表、顶栏菜单与左侧菜单菜单定义中的prefix img_picto(, $this-picto, ...)会自动复用该值。此外若希望 Dolistore 风格市场展示方形 Logo模板还提供了editor_squarred_logo属性注释同样要求图片文件名后跟modulename形式例如myimage.pngmymodule见 modMyModule.class.php。**第 3 步修改业务对象类。**在 myobject.class.php 中把对象的默认fa-file替换为public $picto myobject.pngmymodule;保存后重新进入模块管理页停用再启用模块Dolibarr 会重新读取模块描述并刷新菜单与权限缓存随后在对象卡片、列表行首和新增标签页tab上即可看到自定义图片图标。六、排查要点与最佳实践结合源码可以总结出几个常见坑文件名必须带object_前缀$picto中前的名字与img/下实际文件名必须一致且实际文件要以object_开头。例如$pictomyobject.pngmymodule时文件必须是object_myobject.png否则 L1710 拼出的路径会 404。后必须是模块目录名写错模块名会回退到错误的img/路径界面显示破图。不用写扩展名也可以myobjectmymodule会被自动补全为.png但显式写全扩展名更清晰。不要与非 语法混淆$pictomyobject不带会被当成 Font Awesome 图标渲染为fa-myobject而不是去模块img/找图——这是最常见的误配置。尺寸与格式坚持 16x16 或 32x32 的正方形 PNG若使用.svg矢量图也可被 L1693 的扩展名判断识别。多实体Multicompany环境备用目录遍历逻辑L1697-L1707决定了custom目录下的模块图片同样可用但应避免在main根目录之外重复放置同名文件造成路径歧义。七、延伸阅读模块图片目录约定原文img/README.mdimg_picto()完整实现与 语法解析html.lib.php模块描述类中$picto、editor_squarred_logo的声明与注释modMyModule.class.php业务对象类中对象级$picto的声明myobject.class.php模块模板整体结构与安装部署说明template/README.md赞分享企业应用后端【免费下载链接】dolibarrDolibarr ERP CRM is a modern software package to manage your company or foundations activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). its an open source Web application (written in PHP) designed for businesses of any sizes, foundations and freelancers.项目地址https://gitcode.com/gh_mirrors/do/dolibarr点击查看免费下载相关推荐lnd 发布签名密钥目录scripts/keys完全指南命名规则、签名与验证机制lnd 发布签名密钥目录scripts/keys完全指南命名规则、签名与验证机制 本文以 lnd 仓库中的 scripts/keys/README.md区块链Lucide 图标以图片形式使用lucide-static 中 img 标签与 CSS 背景图完整指南Lucide 图标以图片形式使用 lucide static 中 img 标签与 CSS 背景图完整指南 本文聚焦 Lucide 图标库中 lucide s前端UI组件设计系统Front-End-Checklist 图片规则实战picture img 回退的格式选择与艺术指导完整指南Front End Checklist 图片规则实战 picture img 回退的格式选择与艺术指导完整指南 本指南围绕 Front End Che上一篇10分钟上手Material-UI从原型到交互的零代码界面设计方案下一篇Next.js与Strapi GraphQL内容API查询优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考