更改

DiscuzX3.x模板插件开发

添加903字节, 2022年11月30日 (三) 10:51

无编辑摘要

我们鼓励并推荐，使用插件机制进行个性需求定制和研发。

插件设计的准备工作

'''插件实现流程'''

开始编写社区插件，您应当首先对插件实现的流程有一个大致的了解，以下是我们推荐的插件编写流程：

∙

∙如果需要公开您的插件，可以用插件导出的方式，将插件配置信息导出到一个 XML 文件中，连同相应的程序和模板文件一同打包。同时，编写一个适合新手的插件的说明书也是必不可少的，其中包括：插件适用的 Discuz! 版本、功能概述、兼容性声明、安装方法、使用方法、卸载方法等等。

∙将插件提供给他人，或自己使用，根据使用者反馈，对插件进行完善。插件实现流程至此结束。

∙ '''文件命名规范'''

Discuz! 按照如下的规范对程序和模板进行命名，请在设计插件时尽量遵循此命名规范：

∙可以直接通过浏览器访问的普通程序文件，以 .php 后缀命名。

∙预置读入了每个模块的各种设置变量。

∙[X2.5变更内容] $_G['username'] 将不进行 addslashes 处理

'''插件接口概述'''

使用管理员账号登录 Discuz! 管理中心，在顶部菜单将可以看到“插件”菜单。“插件列表”列出了所有已安装的插件，是控制插件打开与否、设计插件模块、菜单、参数和使用权限的地方，插件开发者可以依照设计意图，在此进行插件的初步设置，这里同时也提供插件导入和插件开关的功能，用于导入他人设计的插件和对插件的可用状态进行变更。

开始编写一个新插件，请首先打开 config/config_global.php 文件，在文件结尾添加以下代码开启插件设计者模式。

在插件管理中添加插件后，仅仅是增加了一条插件记录，后面还需要很多相关的设计和设置。在列表中选择插件的“详情”进入插件的详细设置。插件设置分为三个部分：

∙

'''插件模块''' 插件模块分为程序链接、扩展项目和程序脚本 3 类：

程序链接主导航项目：可在主导航栏增加一个菜单项，可自主指派菜单链接的 URL，也可以调用插件的一个模块，模块文件名指派为 source/plugin/插件目录/插件模块名.inc.php”。注意：由于引用外部程序，因此即便设置了模块的使用等级，您的程序仍需进行判断使用等级是否合法。

∙程序链接主导航项目 - 插件菜单：可在主导航栏的插件子菜单中增加一个菜单项。

扩展项目模块可以在社区的特定位置扩展出新的功能，通常用于扩展新的设置项目。项目的脚本文件以 .inc.php 结尾（如 test.inc.php），模版为固定文件名，位于插件目录的 template/ 子目录中，文件名与脚本名同名（如 test.htm），扩展名为 .htm。添加相应的扩展项目模块时，需注明程序模块、菜单名称。例如我们添加个人面板项目，程序模块为 test，菜单名称是“测试”，当插件启用后，个人面板即家园的设置中会出现“测试”拓展项目。

在新插件内核中，通过 plugin.php 方式访问的插件可直接通过 plugin.php?id=xxx:yyy 方式调用而无需再在后台定义为普通脚本模块，只要 source/plugin/xxx/yyy.inc.php 文件存在即可。如果 xxx 和 yyy 同名，可直接通过 plugin.php?id=xxx 方式访问。

'''插件变量配置'''

插件接口中提供了一个通用的插件配置管理程序，在大多数情况下可实现插件的参数配置，省却了插件开发者自行编写后台管理模块（即上面提到的“扩展项目管理中心”模块）的麻烦。通常情况下，应优先使用通用插件配置管理程序来实现插件的参数配置，只有在通用程序确实无法实现时，才自行编写后台管理模块。输入配置名称和配置变量名、选择合适的配置类型后，即可为此插件增加一个配置变量，点“详情”可以编辑此配置变量的更多信息。为了方便插件程序调用使用者配置好的参数，配置变量同样被存放在了缓存文件中，读取方法将在后面的《插件的参数读取与缓存控制》中详细说明。

注意：您只有在插件管理中将插件设置为“可用”，以上设置才能生效。

'''插件的参数读取与缓存控制'''

∙编写插件程序时，可能需要读取一些插件的信息，如果插件需要使用者进行配置，还需要读取使用者设置的参数值。Discuz! 允许插件程序使用数据库读取和缓存读取这两种方法获取插件信息和参数。Discuz! 的插件接口已经对插件信息进行了合理的缓存，使用缓存读取的方式，将比数据库读取速度更快，消耗的资源更是几乎可以忽略不计。缓存读取唯一的局限是需要插件使用插件接口提供的通用后台管理程序。如果使用自定义后台模块的方式，需要后台模块将参数存放到 pluginvars 数据表中，才能被系统正常缓存。我们强烈推荐您通过缓存读取插件信息和配置数据。

∙

由于调用系统缓存统一通过“loadcache()”函数调用，并存放于 $_G['cache'] 中，因此“loadcache('plugin')”后插件的变量缓会存放于 $_G['cache']['plugin'] 中。嵌入点插件和以 plugin.php 为主脚本调用的插件无需加载此缓存，系统已自动加载了缓存。变量配置类型为“版块/*”的变量会保存在 $_G['cache']['forums'][fid]['plugin'] 中。变量配置类型为“用户组/*”的变量会保存在 $_G['cache']['usergroup_groupid']['plugin'] 和 $_G['group']['plugin'] 中。

'''页面嵌入模块开发'''

页面嵌入类型脚本格式<?php//全局嵌入点类（必须存在）class plugin_identifier {

function HookId_1() {

print_r($_POST);}

plugin_identifier 类中的其它函数为了便于阅读建议以“_”开头，如：

<?phpclass plugin_sample {

function _updatecache() {

......

......}?>

插件嵌入点列表

· '''全局(common/)''' extcredits.htm

string spacecp_credit_extra faq.htm

string faq_extra footer.htm

string global_usernav_extra3

string global_usernav_extra4 (X2.5)

· '''论坛(forum/)'''

collection_all.htm (X2.5)

string collection_index_top

array viewthread_endline viewthread_trade.htm

array viewthread_trade_extra

· '''群组(group/)'''

group.htm

string group_navlink

string index_side_top

string index_side_bottom

· '''家园(home/)'''

editor_image_menu.htm (X3)

string spacecp_blog_upload_extend

string space_home_doing_sync_method space_wall.htm

string space_wall_face_extra

· '''注册/登录(member/)'''

login.htm

string logging_side_top

string register_logging_method

string register_bottom

· '''门户(portal/)'''

portalcp_article.htm

string portalcp_top

string view_article_side_top (X2.5)

string view_article_side_bottom (X2.5)

· '''排行榜(ranklist/)'''

side_left.htm

string ranklist_nav_extra

· '''搜索(search/)'''

album.htm

string album_top

string portal_top

string portal_bottom

· '''应用(userapp/)'''

userapp_app.htm

string userapp_app_top

string userapp_menu_middle

string userapp_menu_bottom

· '''手机全局(mobile/common/)'''

footer.htm

string global_footer_mobile header.htm

string global_header_mobile

· '''手机论坛(mobile/forum/)'''

discuz.htm

string index_top_mobile

array viewthread_postbottom_mobile

string viewthread_bottom_mobile

· '''手机论坛(wml/forum/)'''

discuz.htm

string index_top_mobile

array viewthread_postbottom_mobile

string viewthread_bottom_mobile

'''特殊主题模块开发'''

∙特殊主题模块用于创建一个特殊主题，特殊主题类型脚本格式

<?phpclass threadplugin_identifier {

}}?>

identifier 插件的唯一标识符，在插件设置中设置。

'''函数名以及含义''' 函数名 含义

newthread()

发主题时页面新增的表单项目，通过 return 返回即可输出到发帖页面中

newthread_submit()

主题发布后的数据判断

newthread_submit_end()

主题发布后的数据处理

editpost()

编辑主题时页面新增的表单项目，通过 return 返回即可输出到编辑主题页面中

editpost_submit()

主题编辑后的数据判断

editpost_submit_end()

主题编辑后的数据处理

newreply_submit_end()

回帖后的数据处理

viewthread()

查看主题时页面新增的内容，通过 return 返回即可输出到主题首贴页面中 '''第三方拓展类的开发''' '''目录 [隐藏]''' ∙ 1 广告类 ∙2 道具类 ∙3 任务类 ∙4 验证问答类 ∙5 验证码类(Discuz! X2.5 新增)

~~第三方拓展类的开发~~ ~~目录 [隐藏]~~∙~~1 广告类∙2 道具类∙3 任务类∙4 验证问答类∙5 验证码类(Discuz! X2.5 新增)~~ 广告类 脚本位置：source/class/adv/adv_name.php 语言包位置：source/language/adv/lang_name.php 【Discuz! X3.0 新增】 脚本位置：source/plugin/插件目录/adv/adv_name.php 缩略图：source/plugin/插件目录/adv/adv_name.gif <?phpclass adv_name {

var $version = '1.0';//脚本版本号

var $name = 'name';//广告类型名称 (可填写语言包项目)

'create' => '$adcode = $codes[$adids[array_rand($adids)]];',

);

}}?>道具类 脚本位置：source/class/magic/magic_name.php 语言包位置：source/language/magic/lang_name.php '''【Discuz! X3.0 新增】''' 脚本位置：source/plugin/插件目录/magic/magic_name.php 图标：source/plugin/插件目录/magic/magic_name.small.gif、source/plugin/插件目录/magic/magic_name.gif <?phpclass magic_name {

var $version = '1.0';//脚本版本号

var $name = 'name';//道具名称 (可填写语言包项目)

}

function show($magic) {//道具显示

}}?> 任务类 脚本位置：source/class/task/task_name.php 语言包位置：source/language/task/lang_name.php 【Discuz! X3.0 新增】 脚本位置：source/plugin/插件目录/task/task_name.php 图标：source/plugin/插件目录/task/task_name.gif <?phpclass task_name {

var $version = '1.0';//脚本版本号

var $name = 'name';//任务名称 (可填写语言包项目)

}

function upgrade() {//任务升级的附加处理

}}?> 验证问答类 脚本位置：source/class/secqaa/secqaa_name.php 语言包位置：source/language/secqaa/lang_name.php 【Discuz! X3.0 新增】 脚本位置：source/plugin/插件目录/secqaa/secqaa_name.php <?phpclass secqaa_name {

var $version = '1.0';//脚本版本号

var $name = 'name';//验证问答名称 (可填写语言包项目)

var $copyright = 'Comsenz Inc.';//版权 (可填写语言包项目)

function make(&$question) {//返回安全问答的答案和问题 ($question 为问题，函数返回值为答案)

}}?> 验证码类(Discuz! X2.5 新增) 脚本位置：source/class/seccode/seccode_name.php 语言包位置：source/language/seccode/lang_name.php 【Discuz! X3.0 新增】 脚本位置：source/plugin/插件目录/seccode/seccode_name.php <?phpclass seccode_name {

var $version = '1.0';//脚本版本号

var $name = 'name';//验证码类型名称 (可填写语言包项目)

}

function make() {//输出验证码，echo 输出内容将显示在页面中

}}?> 计划任务模块开发 ∙本功能为 Discuz! X3.0 新增内容 ∙计划任务模块用于拓展一个计划任务项目，本模块会在插件安装时自动添加到系统计划任务中，并在插件卸载时自动从中删除 脚本位置：source/plugin/插件目录/cron/cron_name.php <?php//cronname:mycron

计划任务名称，可写脚本语言包中的项目//week:1

设置星期几执行本任务，留空为不限制//day:1

设置哪些分钟执行本任务，至多可以设置 12 个分钟值，多个值之间用半角逗号 "," 隔开，留空为不限制if(!defined('IN_DISCUZ')) {

exit('Access Denied');}//您的计划任务脚本内容?>

'''缓存更新模块开发''' ∙本功能为 Discuz! X3.0 新增内容 ∙缓存更新模块用于在系统更新缓存时拓展一个缓存更新项目 脚本位置：source/plugin/插件目录/cache/cache_name.php <?phpif(!defined('IN_DISCUZ')) {

exit('Access Denied');}function build_cache_plugin_name() {

//您的缓存更新脚本内容}?> 插件安装、卸载、升级脚本的设计 目录 [隐藏]

∙

1 安装、卸载 ∙2 升级 ∙3 检测 ∙4 授权协议、插件介绍 ∙5 Discuz! 版本兼容性设置 ∙6 其他论坛数据导入 ∙7 小提示 '''安装、卸载'''插件作者可以设计 2 个脚本文件用于插件的安装和卸载，文件名任意。脚本中可用 runquery() 函数执行 SQL 语句，表名可以直接写“cdb_”。插件作者只需在导出的 XML 文件结尾加上安装、卸载脚本的文件名即可

</item> </root> 安装、卸载程序中可随意设计页面的跳转，只要在插件安装、卸载结束时候输出添加以下代码即可。 $finish = TRUE;升级 插件作者可以设计一个脚本文件用于插件的升级，文件名任意。脚本中可用 runquery() 函数执行 SQL 语句，表名可以直接写“cdb_”。插件作者只需在导出的 XML 文件结尾加上升级脚本的文件名即可

</item> </root> 升级程序中可通过 $fromversion 和 $toversion 变量判断升级的具体版本号，并随意设计页面的跳转，只要在插件升级结束时候输出添加以下代码即可。 $finish = TRUE; 插件的当前版本号位于 XML 文件的以下分支中，可自行更改。

......

......

</item>检测 插件作者可以设计一个脚本文件用于插件在安装、卸载、升级操作前的检测，文件名任意。插件作者只需在导出的 XML 文件结尾加上检测脚本的文件名即可

</item> </root>授权协议、插件介绍 插件在安装的时候您可以自定义授权信息文本，文本支持 Discuz! 代码，站长同意后才能安装插件。如果插件存在后台管理界面或者变量配置，那么插件介绍文本会显示在插件后台页面中。插件作者只需在导出的 XML 文件结尾加上以下内容即可

</item> </root>Discuz! 版本兼容性设置 请仔细检查您的插件是否可以在相应的 Discuz! 版本中运行。然后在 XML 文件的以下分支中自行更改。 如您的插件兼容多个版本，请用逗号(,)分隔，如“X2,X2.5”（此写法从 Discuz! X2 R20120329 后开始支持）

......

</item>其他论坛数据导入 插件安装时可以直接导入一个或多个论坛数据，这些论坛数据包括表情(smilies)、风格(styles)的数据。在导出的 XML 文件结尾加上需要导入数据的类型和数据文件名即可，多个文件名用逗号(",")分隔。

</item>

</item> </root>小提示 如果导出的 XML 文件名以 SC_GBK、SC_UTF8、TC_BIG5、TC_UTF8 结尾，显示的时候将直接显示为“简体”、“繁体”、“UTF8”等字样。 插件模板和语言包的设计 插件语言包创建语言包 ∙给插件创建语言包首先需要创建一个 data/plugindata/identifier.lang.php 文件，文件内容中包含 4 个数组，如下： <?php$scriptlang['identifier'] = array( 'english' => 'chinese', ...);$templatelang['identifier'] = array( 'english' => 'chinese', ...);$installlang['identifier'] = array( 'english' => 'chinese', ...);$systemlang['identifier'] = array( 'file' => array(

'english' => 'chinese',

... ), ...);?> $scriptlang 为程序脚本文件的语言包。 $templatelang 为模版文件的语言包。 $installlang 为安装、升级、卸载脚本用的语言包。 $systemlang 为系统语言包(Discuz! X3 新增)。 如果插件不涉及某些类型的语言文字，变量可忽略。 ∙ 然后在插件基本设置中开启语言包选项后即可。 '''调用语言包''' 模版中调用模板文件语言包，通过 {lang identifier:english} 方式调用。 程序脚本中调用脚本文件语言包，通过 lang('plugin/identifier', 'english') 方式调用。 安装脚本中调用安装脚本文件语言包，通过 $installlang 变量直接获取。如 $installlang['english']。 系统语言包用于替换系统语言包中的某些语言条目。 '''语言包导出''' 创建好的语言包在插件导出后会自动导出到 XML 文件中，供插件作者转码后发放多编码版本的插件。如上例中导出的 XML 中会包含以下内容： <item id="language">

</item>

</item></item> data/plugindata/identifier.lang.php 文件不必在插件发布的时候导出，此文件仅供插件设计者模式时使用。 '''插件模板''' 插件的模板统一放置到 source/plugin/identifier/template 目录下，程序脚本通过以下语句调用插件模板文件，如下例，调用 source/plugin/identifier/template/test.htm include template('identifier:test'); 模版中调用插件模版通过以下方法： {template identifier:test} 插件注册及插件新版本提示 以下内容仅限 Discuz! X2.0 为了保护插件的合法权益，你可以把设计好的插件到官方的应用中心( http://addon.discuz.com )进行注册，注册后你将拥有此插件的唯一所有权。 插件 LOGO 设置 设置插件的 LOGO，提升插件的价值。请自行设计一个 40x40 大小的 PNG 图片，上传到扩展中心，此 LOGO 会在 Discuz! 的插件管理中心显示。 插件新版本提示 插件新版本提示可以让站长在随时检测到你插件是否存在新版本。请插件作者把自己发布插件的相关文件生成 MD5 校验码，然后到扩展中心进行插件版本校验文件的登记。 插件校验码生成函数 function createValidator($pluginid, $md5files) {

define('IN_DISCUZ', true);

require_once 'source/class/class_xml.php';

fwrite($fp, array2xml($xml));

fclose($fp);

}} 此函数执行后会在插件目录生成 validator.xml 文件，请同插件其他文件一并打包发布。页面输出的 MD5 校验码填写到扩展中心“插件版本校验文件登记”中。 '''使用范例''' $md5files = array(

'source/plugin/myrepeats/switch.inc.php',

'source/plugin/myrepeats/admincp.inc.php',

'source/plugin/myrepeats/discuz_plugin_myrepeats.xml',

'source/plugin/myrepeats/memcp.inc.php',);createValidator('myrepeats', $md5files); '''编写插件的原则与注意事项''' 请在您动手编写插件之前，还需要仔细的阅读以下原则，遵循这些原则，将有效的避免可能发生的问题： ∙所有与插件的程序，包括其全部的前后台程序，请全部放入 source/plugin/ 目录中，同时在插件的安装说明中指出，插件的文件需要复制到哪些目录。为了避免与其他插件冲突，请尽量建立 source/plugin/ 下的子目录，并将插件程序放置于子目录下，这样您编写的插件将获得更好的兼容性。 ∙如果您的插件包含“导航栏”模块，该模块将统一用 plugin.php?identifier=xxx&module=yyy 的方式调用，请在相应链接、表单中使用此方式。其中 xxx 为插件的惟一标识符，yyy 为模块名称。前台插件外壳程序 plugin.php 已经加载了通用初始化模块 /source/class/class_core.php，不需再次引用。 ∙如果您的插件包含“管理中心”模块，该模块将统一用 admin.php?action=plugins&identifier=xxx&pmod=yyy 的方式调用，请在相应链接、表单中使用此方式。其中 xxx 和 yyy 的定义与“导航栏”模块中的相同。系统还允许用 admin.php?action=plugins&edit=$edit&pmod=$mod 的方式来生成链接和表单地址，$edit 和 $mod 变量已经被插件后台管理接口赋值，因此将这两个变量值带入 URL 中也是被支持的。由于后台模块是被 admin.php 调用，因此已加载了通用初始化模块 /source/class/class_core.php 并进行了后台管理人员权限验证，因此模块程序中可直接写功能代码，不需再进行验证。 ∙请勿绕过插件的前后台外壳（plugin.php 和 admin.php）而以直接调用某程序的方式编写插件，因为这样既导致了用户使用不便，代码冗余和不规范，同时又产生了因验证程序考虑不周到而带来的安全隐患。您可以在任何地方，包括链接、表单等处方便的使用上述 URL 地址对插件模块进行调用。 ∙所有与插件有关的程序，包括全部的前台程序，因全部使用外壳调用，请务必在第一行加入 if(!defined('IN_DISCUZ')) { exit('Access Denied');} 后台程序第一行加入 if(!defined('IN_DISCUZ') || !defined('IN_ADMINCP')) { exit('Access Denied');} ∙以免其被 URL 直接请求调用，产生安全问题。 ∙一般情况下，您发布插件请使用插件导出的功能，以方便使用者一次性导入插件的配置数据，极特殊的情况下，也可以分步骤告知使用者如何进行插件配置管理和安装此插件。 ∙如果功能独立，请尽量使用单独程序的方式编写插件（即外挂型插件），而尽量少的对论坛本身代码进行修改，这将为使用者今后的升级带来很大方便。 ∙您可以修改 Discuz! 本身的数据结构，但更推荐在不很影响效率的前提下将插件数据用另外的数据表存储，因为不能排除您增加的字段或索引和今后版本 Discuz! 核心数据字段重名的可能。在任何情况下，请不要删除 Discuz! 标准版本数据结构中已有的字段或索引。

∙请在插件说明书中对插件做以详尽的描述，例如增加了哪些字段、哪些表，修改了或新增了哪些程序，版本兼容性，后续支持的提供方式（例如不提供支持，或以什么样的方式提供）。如果方便，请尽可能提供插件的卸载方法，例如去除哪些字段、删除哪些新增的程序、将哪些被插件修改的程序恢复原状等等，使用者会感激您为此付出的辛勤劳动，甚至愿意支付相应的费用支持您未来的发展。

∙如果插件使用另外的数据表存储，请在插件管理中准确的设置插件所使用的数据表名称（不包含前缀），这样用户在备份数据的时候，能够把插件数据一同备份。 ∙Discuz! 内置了 8 种自定义积分，存储于 common_member 表中的 extcredits1 至 extcredits8 字段中，类型为有符号整数 2、语言包编码转换工具 convertz 【百度一下】（专门用来处理多种编码的插件安装） 3、数据库管理工具 navicat 【百度一下】（方便数据库的查看与操作） 4、网站的基本数据，这些数据包括：系统常量、全局变量、系统调用，首先从系统常量说起 4.1、系统常量

DISCUZ_ROOT

//网站根目录

FORMHASH

//HASH值

其余的可直接打印出来查看，如： 1<?php 2require_once './source/class/class_core.php'; 3$discuz = & discuz_core::instance(); 4$discuz->init(); 5print_r(get_defined_constants()); 6?> 复制代码 4.2、全局变量 直接打印$_G即可得知，如： 7<?php 8require_once './source/class/class_core.php'; 9$discuz = & discuz_core::instance(); 10$discuz->init(); 11print_r($_G); 12?> 复制代码 4.3、数据库配置参数 直接打印$_G['config']['db']即可，如： 13<?php 14require_once './source/class/class_core.php'; 15$discuz = & discuz_core::instance(); 16$discuz->init(); 17print_r($_G['config']['db']); 18?> 复制代码 4.4、数据库操作

DB::table()

//增加了pre的数据库表名

2.3、对于文字内容，记得使用htmlspecialchars（dhtmlspecialchars）

2.4、写入数据库时的注意事项

要进数据库的变量一定得addslashes(DZ内为daddslashes,如用DZ无须再次过滤,DZ已将所有$_POST和$_GET过滤)，当然，如果你进的是数字（比如uid，并且已经intval过），或者是其他一些肯定不会出错的，那么你可以不做这一步。

2.5、在写sql语句时，变量一定得记得用’框起来。如果变量是字符串，不这么做会出错。如果是数字不这么做不会提示出错，但是有可能有注入的危险。

2.6、数组在运用前记得写$xxx = array(); 原因很简单,防止用户提交恶意的值。

小小

1

个编辑

更改

DiscuzX3.x模板插件开发

导航菜单

个人工具

名字空间

变种

视图

更多

搜索

导航

站群链接

工具