我的书签
添加书签
移除书签3.1 Discuz! X5.0：新增模板接口
兼容简述
从 X5.0 开始，为了方便模板开发者对比文件，default 模板已经默认启用了 php 后缀的文件。官方允许存在同时兼容 X3.5、X5.0 的模板应用，但如果您的继承模板文件过多，请仔细核对确保您的模板是否完全兼容 X5.0，避免出现前端展示错误。
细胞模板
细胞模板为全新的模板元素封装机制，可将复杂的模板内容封装为一个 {cell}、{cells} 标记。其中 {cells} 还支持站长自定义模式，站长在后台可随意 DIY。
{cell}
{cell} 为细胞模板的最小元素，可以将模板中的任何内容写于其中，调用方直接写 {cell}。
格式：
{cell file}
file 为文件名，对应 /template/xxx/cell/ 目录下的文件，支持多级目录，文件扩展名目前固定为 .htm。文件中直接填写“细胞体”内容代码即可。
{cells}
{cells} 中可以组合多个 {cell} 元素，可将多个包含 {cell} 的组合再次拼接为一个大的细胞模板。
格式：
{cell file}
file 为文件名，对应 /template/xxx/cell/ 目录下的文件，支持多级目录。
扩展名为 .htm 的模板文件规则同 {cell}，里面可以包含 {cell}。 扩展名为 .php 的模板文件需要书写成 class 类，具体参考“template/default/cells/forum/portal/”目录下的文件。
系统的细胞模板
为了避免第三方模板重复套用一些固定不变的代码，以及避免内核逻辑的缺失，系统已经内置了一些细胞模板，可自行搜索 “template/default” 目录下的 “{cells ” 和 “{cell ” 代码，替换到第三方模板的相应位置。
例如：
登录模板的相应位置加入 “{cells account/icons account/icons}” 即可直接显示 X5 新增的第三方登录
编辑器模板的相应位置加入 “{cells editor/toolbar}” 即可直接让站长自行通过细胞模板后台设置调整编辑器按钮工具栏
更多系统细胞模板期待您的自行摸索
聚合首页
聚合首页设置位于后台“论坛”->“聚合首页”，全新的首页可自定义主题列表展示的规则。设置后可配合细胞模板在后台即可进行 DIY 调整。
模板变量
模板变量完全复刻了插件变量的机制，模板开发者可以直接为自己的模板设计一套参数设置后台，而无需再用插件配合。
设计
开启了开发模式后，模板列表会出现“设计”按钮，点击后进行编辑操作，变量类型与插件变量完全一致。同时还增加了下面 2 个布局分类：
- 标题栏：标题栏可为多个设置项增加一个小标题；
- 分组：分组可为多个设置项进行通过多页切换的方式进行分组，分组会按照设置的显示顺序为设置项进行页面拆分。使用分组时，顺序的第一个项目必须是分组类型；
导出
增加了模板变量的设置后，可重新导出，导出后的 XML 将包含模板变量的内容。
版本号
由于增加了模板变量的功能因此导出的 XML 中可以设置一个 version 的风格变量，标记版本的变化：
<root>
...
<item id="Data">
...
<item id="style">
<item id="version"><![CDATA[1.0]]></item>
...
</item>
<item id="var">
...
</item>
...
</root>
DIY 支持手机版
X5.0 已支持手机版 DIY，您可以按照设计 PC DIY 模板的方式给 touch 目录下的模板文件添加 DIY 元素内容。
语言包扩展
X5.0 的模板文件中可以写自定义的语言包扩展文件，这样在您设计的模板中可以通过“{lang xxx}”语法直接调用您自定义的语言文字，语言包扩展文件为 /template/i18n/SC_UTF8/lang_template.php
$lang = [
'nice' => '不错！',
];
XML 中的 name、tplname、copyright、version、var.title、var.description、var.extra 可以写进 $lang 中
同时，语言包扩展也兼容 i18n，可以针对相应的 i18n 语言定制额外语种的语言包，兼容 i18n 的扩展文件位为 /template/xxx/i18n/en/lang_template.php
$lang = [
'nice' => 'nice!',
];
JS 语言包
模板同样拥有 JS 语言包，关于 JS 语言包的说明参考 “新增插件接口” 中的说明
页面组件、模块组件
在 X5.0 中，您可以把做好的 DIY 整体页面以及模块进行导出放到指定目录。这样用户如果安装了您的模板， 当 DIY 的时候无论当前在哪个模板都可以直接看到您导出的 XML 文件进行导入。这样您可以做一个完整的页面，或者各种页面模块给站长随时给网站添加元素
页面组件，请导出页面的完整配置 XML 文件，将文件放到 /template/xxx/portal/diyxml/page 目录下 模块组件，请导出框架的 XML 文件，将文件放到 /template/xxx/portal/diyxml/module 目录下 同时附带同名的 jpg 文件作为预览图，此图大小 80x60，如 XML 文件名为 abc.xml 那么预览图文件名为 abc.jpg
xml 中可以额外附加一个 name 标记作为组件的名字，如不带此标记默认使用文件名
<!--[name]超帅门户首页[/name]-->
<?xml version="1.0" encoding="ISO-8859-1"?>
<root>
....
头像调用
在 X5.0 中，头像可以用统一方法调用。新方法下，开发者无需再考虑头像是否存在的问题。而且无需再调用 avatar() 函数以及 UCenter，你只需写一个 <img> 添加 data-uid 属性即可。
<img class="_avt" data-uid="$uid" data-size="[small/middle/big]" />
如果已经获取了头像源文件地址，可以用下面的方法避免头像不存在的问题：
<img class="_avt" data-src="$src" />
请注意，要让此方法生效，请确保您的模板无论是 PC 还是 H5 下都调用了官方的 common.js 和 mobile/common.js 文件，同时 default 模板 common/header_common 中需要新增以下全局 JS 变量
DEFAULTAVATAR = '$_G[setting][defaultavatar]'
安装时可用的扩展功能（X5.0.4起生效）
从 X5.0.4+ 版本开始模板安装的 JSON 文件里可以添加如下额外的功能。当然如果你是 XML 格式的文件也可以，但此处以 JSON 文件举例。以下功能只负责在模板安装的时候执行，卸载的时候不会执行反向操作。有了这些扩展功能，你可以免去很多安装完毕后的前置配置的指导。
添加聚合首页数据
如果模板涉及聚合首页功能，可以在模板安装的时候添加聚合首页的数据，格式如下：
"forumportal": [
{
"from": "identifier",
"display_order": "",
"name": "首页",
"allow": "1",
"adminid": "0",
"group_fids": "",
"authorids": "",
"follow": "0",
"digest": "0",
"displayorder": "0",
"heats": "0",
"recommends": "0",
"dateline": "0",
"laspost": "0",
"order_before": "0",
"order": "0"
}
],
可以添加多条，其中 from 为自定义的一个唯一标识，避免多次安装时重复添加。其他值可自行参考管理中心中聚合首页的配置项。
添加默认首页
如果模板设计了自己的首页，可以通过此功能设置首页页面的 URL，如果此 URL 在主导航中不存在会自动添加命名为“首页”的一条记录。
"defaultindex": "portal.php",
添加 DIY 数据
模板安装的时候，可以默认导入 DIY 数据，免去用户自己打开 DIY 面板导入的操作。
"diy": [
{
"filename": "forum_forumdisplay.xml",
"tplname": "forum/forumdisplay"
},
{
"filename": "forum_viewthread.php",
"tplname": "forum/viewthread"
}
],
可以添加多条，filename 填写位于 portal/diyxml/ 目录下的文件名，tplname 为导入的目标模板。
添加 setting 表数据
安装模板时同时修改 setting 表的数据，请务必确定变量名和值的正确性。
"setting": {
"close_leftinfo": "1",
"close_leftinfo_userctrl": "0"
}
整理自 Discuz! 官方开放平台技术文档（open.dismall.com），由 WorkBuddy 整理发布。
