> ## Documentation Index
> Fetch the complete documentation index at: https://discuz.p.cafe/llms.txt
> Use this file to discover all available pages before exploring further.

# 新增模板接口

## **兼容简述**

从 X5.0 开始，为了方便模板开发者对比文件，default 模板已经默认启用了 php 后缀的文件。官方允许存在同时兼容 X3.5、X5.0 的模板应用，但如果您的继承模板文件过多，请仔细核对确保您的模板是否完全兼容 X5.0，避免出现前端展示错误。

## **细胞模板**

细胞模板为全新的模板元素封装机制，可将复杂的模板内容封装为一个 `{cell}`、`{cells}` 标记。其中 `{cells}` 还支持站长自定义模式，站长在后台可随意 DIY。

`{cell}` 为细胞模板的最小元素，可以将模板中的任何内容写于其中，调用方直接写 `{cell}`。

**格式：**

```
{cell file}
```

file 为文件名，对应 `/template/xxx/cell/` 目录下的文件，支持多级目录，文件扩展名目前固定为 `.htm`。文件中直接填写"细胞体"内容代码即可。

`{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]'
```