amis Tpl 模板组件完全指南从变量插值到事件派发【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amisTpl 是 amis 低代码框架中用于输出模板文本/HTML的通用组件通过type: tpl配合tpl属性即可把数据域中的变量渲染进页面是列表、表格、卡片等场景中最常使用的展示型组件。读完本文你将掌握 Tpl 的完整配置属性、数据映射与过滤器用法、JavaScript 模板引擎语法以及基于onEvent的点击/悬停事件派发方案。一、Tpl 是什么在 amis 中绝大多数文案类展示如表格单元格、卡片标题、面包屑分隔符、提示内容等都可以由一个 Tpl 完成。官方文档对其定位的描述非常简短输出模板的常用组件。也就是说Tpl 是 amis 模板能力在前端组件层的统一出口底层由 packages/amis/src/renderers/Tpl.tsx 实现并通过Renderer({type: tpl, alias: [html]})注册见 Tpl.tsx因此它还有一个别名html即{type: html, html: ...}与{type: tpl, tpl: ...}等价。从源码结构看Tpl 组件支持tpl、html、text、raw四种内容来源并内置inline: true默认以span渲染、内联显示与空值placeholder默认空字符串两个默认属性见 Tpl.tsx这为后续各类属性讲解提供了实现依据。二、基本用法让静态页面活起来在数据域中放置变量然后用${变量名}在模板中引用{ data: { text: World! }, type: page, body: { type: tpl, tpl: Hello ${text} } }页面输出为Hello World!。这里type固定为tpltpl即模板字符串。完整的模板语法体系在模板文档中有详细说明本文后续会结合 Tpl 逐一展开。关于变量取值需要了解 amis 的数据映射${xxx}或$xxx机制它的完整规范记录在数据映射中核心能力包括链式取值${company.name}可逐层访问嵌套对象转义输出想输出字面量${xxx}需在$前加反斜杠写成\${xxx}命名空间取值1.1.6 起${window:document.title}、${ls:key}、${ss:key}、${cookie:key}分别读取全局变量、localStorage、sessionStorage 与 cookies过滤器${xxx | filter1 | filter2}支持串联处理。这些取值能力在 Tpl 中的实际解析入口是 amis-core 的filter/asyncFilter函数packages/amis-core/src/utils/tpl.ts它按注册顺序依次让各模板引擎认领字符串命中即编译。三、渲染 HTML 与安全转义Tpl 输出的是 HTML最终通过dangerouslySetInnerHTML注入见 Tpl.tsx因此模板中可以内嵌标签{ data: { text: World! }, type: page, body: h1Hello/h1 span${text}/span }默认情况下变量内容会经过html 转义内置引擎的默认过滤器为| html见 packages/amis-core/src/utils/tpl-builtin.ts所以当变量本身携带 HTML 时需要用raw过滤器关闭转义{ data: { text: bWorld!/b }, type: page, body: h1Hello/h1 span${text|raw}/span }安全提醒raw意味着不经过滤直接输出动态渲染用户可控内容极易引发XSS攻击。官方文档明确警告使用raw时请确保变量内容可信永远不要渲染用户填写的内容见数据映射的 raw 小节。四、Tpl 属性表详解Tpl 的核心属性如下对应文档属性表属性名类型默认值说明typestringtpl指定为 Tpl 组件亦可写html源码中的别名classNamestring外层 DOM 节点的类名tpl模板配置模板字符串/模板引擎语法showNativeTitleboolean是否把文本内容设置到外层 DOM 的title属性鼠标悬停显示className定制外层样式className会通过 classnames 库合并到组件根节点上Tpl.tsx。常见用法如给单元格文本加间距或颜色类{ type: tpl, tpl: 重要提示, className: text-danger m-l-sm }showNativeTitle悬停显示全文开启后Tpl 会把渲染出的文本内容写入外层 DOM 的title属性鼠标悬停时浏览器会弹出原生提示。源码中使用DOMParser解析内容并提取纯文本剔除 HTML 标签作为 title见 Tpl.tsx因此即使模板包含富文本title 也只会显示纯文本{ type: tpl, tpl: 这是一段很长的说明文字, showNativeTitle: true }源码中未被文档列出的扩展属性从 AMISTplSchema 类型定义看Tpl 还支持若干文档属性表未提及、但实际可用的能力可视为对属性表的补充html/text/raw除tpl外的三种内容源优先级为raw html tpl text见 Tpl.tsx。其中text会强制对结果做escapeHtml转义适合纯文本展示inline是否内联显示默认true为false时外层渲染为divwrapperComponent自定义外层标签style支持样式对象且支持用数据映射动态计算经buildStyle处理maxLine文本超出指定行数时截断显示设置WebkitLineClampbadge角标配置placeholder值为空时的占位内容默认空字符串value不写模板时直接渲染传入的 value对象会自动JSON.stringify。例如一个带行数截断的纯文本 Tpl{ type: tpl, text: ${intro}, maxLine: 2 }五、模板能力纵深Tpl 背后的两套模板引擎Tpl 的tpl属性支持两种语法体系它们由 amis-core 的模板引擎注册机制统一调度filter会遍历已注册引擎命中test即使用对应引擎编译packages/amis-core/src/utils/tpl.ts目前默认注册了builtin与lodash两个引擎tpl.ts。两种语法不能混用完整说明见模板文档的注意事项章节。1. 内置模板字符串默认引擎builtin用${xxx}从数据域取值支持链式与过滤器识别规则检测$字符且其后不是引号/空格、且未被\转义见 tpl-builtin.ts变量缺失或为空时默认显示空可用| default过滤器兜底。2. 表达式语法1.5.0${xxx}内可以直接写三元表达式或调用公式函数{ type: tpl, tpl: ${xxx 1 ? One : Others} }表达式由 amis-formula 的parse/evaluate求值见 packages/amis-core/src/utils/tpl.ts完整的表达式能力见表达式文档。3. JavaScript 模板引擎lodash template当模板中出现%时字符串会交给 lodash 引擎语法与 ejs 类似% 输出 %、% JS 语句 %。注意此时取变量要用data.xxx因为 lodash 引擎把数据域作为模板作用域variable: data见 packages/amis-core/src/utils/tpl-lodash.ts{ type: page, data: { user: no one, items: [A, B, C] }, body: [ { type: tpl, tpl: User: %- data.user % }, { type: divider }, { type: tpl, tpl: % if (data.items data.items.length) { %Array: % data.items.forEach(function(item) { % span classlabel label-default%- item %/span % });} % } ] }引擎内部通过template(str, {imports, variable: data, interpolate: /%([\s\S]?)%/g})编译其中刻意禁用了 lodash 默认的${xxx}插值语法避免与内置模板字符串冲突tpl-lodash.ts。lodash 引擎额外注入了以下工具方法见 tpl-lodash.ts方法说明formatDate(value, formatLLL, inputFormat)格式化时间format 遵循 moment 语法formatTimeStamp(value, formatLLL)时间戳转格式化字符串内部即 date 过滤器formatNumber(number)数字千分位格式化内部即 number 过滤器countDown(value)倒计时显示距指定时间戳还剩多少天已过期显示已结束momentmoment 对象本身也可直接用同时模板字符串章节的全部过滤器如date、number在 lodash 引擎中也能以函数形式调用例如%- date(data.xxx, YYYY-MM-DD) %。两种语法不可交叉混用{ type: tpl, tpl: ${data.xxx a} }上面是错误写法——内置引擎中应直接写${xxx a}而不是data.xxx反之在% %中则必须用data.xxx取值。两种取值风格混用是初学者最容易踩的坑。六、数据映射与常用过滤器实战Tpl 模板中频繁用到的过滤器完整清单见数据映射的过滤器章节以下为高频实用的几个{ type: page, data: { html: div这是一段codehtml/code/div, price: 233333333, now: 1586865590, value: , array: [a, b, c] }, body: [ { type: tpl, tpl: html is: ${html|raw} }, { type: tpl, tpl: price is ${price|number} }, { type: tpl, tpl: now is ${now|date:YYYY-MM-DD} }, { type: tpl, tpl: value is ${value|default:-} }, { type: tpl, tpl: array is ${array|join} } ] }raw输出原始 HTML注意 XSS 风险html显式按 HTML 显示变量默认即走 html 转义json[:tabSize]对象格式化为 JSON 字符串如${info|json:4}toJsonJSON 字符串转对象date[:format][:inputFormat]时间格式化默认输出LLL本地化格式默认按秒时间戳X解析毫秒需指定x参数中的:需用\转义如${now|date:LLL:YYYY/MM/DD HH\:mm\:ss}number千分位percent[:decimals]转百分比默认 0 位小数round[:decimals]四舍五入默认保留 2 位truncate[:length][:mask]超长截断默认 200 字符、省略号...default[:defaultValue]空值兜底split[:delimiter]/join[:separator]字符串与数组互转fromNow相对时间1.4.0。过滤器支持串联例如 上个月第一天 的经典写法{ type: page, body: 上个月第一天是${_|now|dateModify:subtract:1:month|dateModify:startOf:month|date:YYYY-MM-DD HH\\:mm\\:ss} }1.5.0 起官方更推荐函数调用式写法如${html(xxx)}替代${xxx|html}详见表达式文档中的新表达式语法。七、事件派发click / mouseenter / mouseleave从2.5.3版本开始Tpl 会对外派发以下事件见事件表可以通过onEvent监听并通过actions配置执行动作事件数据用${事件参数名}或${event.data.[事件参数名]}获取完整的事件动作机制见事件动作事件名称事件参数说明click-点击时触发mouseenter-鼠标移入时触发mouseleave-鼠标移出时触发三个事件在源码中分别对应onClick、onMouseEnter、onMouseLeave处理函数统一调用dispatchEvent(e, data)派发见 Tpl.tsx因此事件上下文里可通过event.context.nativeEvent拿到原生鼠标事件对象。click 示例{ type: tpl, tpl: Hello, onEvent: { click: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.context.nativeEvent.type} } } ] } } }点击文本后弹出 toast内容为原生事件类型click。mouseenter 示例{ type: tpl, tpl: Hello, onEvent: { mouseenter: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.context.nativeEvent.type} } } ] } } }mouseleave 示例{ type: tpl, tpl: Hello, onEvent: { mouseleave: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.context.nativeEvent.type} } } ] } } }三个事件常组合使用例如移入时高亮、移出时还原、点击时跳转的交互卡片actions也支持reload、setValue、ajax、dialog、link等多种动作类型均可在事件动作文档中查阅。八、实现原理与源码路径速查梳理 Tpl 的完整调用链便于读者深入源码注册TplRenderer通过Renderer({type: tpl, alias: [html]})注册见 packages/amis/src/renderers/Tpl.tsx内容解析组件根据raw/html/tpl/text的优先级选择模板源调用filter同步或asyncFilter异步支持异步表达式编译见 Tpl.tsx引擎调度filter遍历已注册引擎见 packages/amis-core/src/utils/tpl.ts内置引擎注册于 tpl.ts内置引擎负责${xxx}模板字符串与过滤器实现在 packages/amis-core/src/utils/tpl-builtin.tslodash 引擎负责% %语法实现在 packages/amis-core/src/utils/tpl-lodash.ts输出编译结果经env.filterHtml过滤后通过dangerouslySetInnerHTML注入见 Tpl.tsx并支持setThemeClassName主题类名与CustomStyle自定义样式注入。组件在仓库中的使用与测试覆盖非常广泛可作为参考实践如 packages/amis/tests/renderers/Each.test.tsx 展示了 Tpl 在循环中的% data.item %用法packages/amis/tests/renderers/Carousel.test.tsx 展示了 Tpl 输出背景图样式的写法packages/amis/tests/renderers/AMISRender.test.tsx 则验证了最基础的type: tpl渲染。九、常见问题小结模板不生效确认tpl值是否为字符串且${}与% %未混用HTML 被转义显示为源码变量内容需要原样输出时用| raw但要评估 XSS 风险时间格式不对先确认数据是秒X默认还是毫秒x再设置inputFormat悬停不显示 title检查showNativeTitle是否开启且注意 title 内容为纯文本HTML 标签会被剥离lodash 模板中取不到值% %内必须用data.xxx而不是${xxx}事件不触发确认 amis 版本 ≥ 2.5.3且onEvent中的actionType拼写正确。十、延伸阅读模板概念文档两种模板引擎的完整语法与注意事项数据映射文档${xxx}取值、命名空间、过滤器全量清单表达式文档1.5.0 新表达式语法与内置函数事件动作文档onEvent与actions的完整配置说明【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考