企业官网建设流程全解析

amis Mapping 组件怎么按映射值渲染文本、HTML 或其他组件

【免费下载链接】amis前端低代码框架，通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis

amis 是前端低代码框架，页面通过 JSON 配置生成。当页面上某个字段的值只有有限几种取值（比如订单状态、开关标志），需要用不同的文本、带样式的 HTML 标签甚至完全不同的组件来展示时，就可以用mapping（Mapping 映射）组件：给它一个value和一份map映射表，它负责把值转换成对应的展示内容，未命中时走*兜底。完整属性说明见 Mapping 映射。

本文按展示复杂度的顺序走一遍配置路径：纯文本 → HTML → 其他 amis 组件 → 自定义模板 → 数组映射 → 作为表单/表格字段使用 → 远程字典。

准备条件

先能渲染出一个 amis 配置。amis 有两种用法：JS SDK（外链 js 即可，适合非 React 项目）和 React（npm i amis，React>=16.8.6、mobx^4.5.0，见 快速开始）。配置本身是 JSON，顶层节点必须是type: "page"，页面内容放在body里，树形结构规则见 配置与组件。

本文所有示例都是一个page包一个mapping节点的完整 schema，替换渲染处的 amisJSON 即可生效。

用 map 按映射值渲染文本

最基本形态：value是待匹配的值，map是 k-v 对象，key 为匹配值，value 为展示文本；*是兜底项，命中不到其他 key 时展示它。

{ "type": "page", "body": { "type": "mapping", "value": "1", "map": { "1": "第一", "2": "第二", "3": "第三", "*": "其他" } } }

value为"1"时页面展示「第一」。把value改成"5"这类未配置的值，就展示*对应的「其他」。

如果值可能不存在（例如接口还没返回或字段为空），用placeholder控制数据不存在时的展现：

{ "type": "page", "body": { "type": "mapping", "placeholder": "数据不存在", "map": { "1": "第一", "2": "第二", "3": "第三", "*": "其他" } } }

渲染 HTML

map的 value 可以是 HTML 字符串，渲染后直接作为标签展示。HTML 里还能用${xxx}模板语法取数据域里的变量，比如兜底项中回显原始值：

{ "type": "page", "body": { "type": "mapping", "value": "2", "map": { "1": "<span class='label label-info'>漂亮</span>", "2": "<span class='label label-success'>开心</span>", "3": "<span class='label label-danger'>惊吓</span>", "4": "<span class='label label-warning'>紧张</span>", "*": "<span class='label label-default'>其他：${type}</span>" } } }

上例value为"2"，页面展示label-success样式的「开心」标签。这套label label-*类名来自 amis 自带的 helper.scss 样式体系。

渲染其他 amis 组件

map的 value 也可以是 amis schema 节点，这样不同映射值可以渲染完全不同的组件，例如一个tag、一个tpl，再加一个普通字符串兜底：

{ "type": "page", "body": { "type": "mapping", "value": "1", "map": { "1": { "type": "tag", "label": "#4096ff", "displayMode": "rounded", "color": "#4096ff" }, "2": { "type": "tpl", "tpl": "2" }, "*": "其他" } } }

有一个必须记住的限制：配置了itemSchema后，映射值不会再作为 schema 渲染，此时渲染交给itemSchema模板接管（下一节）。

用 itemSchema 渲染自定义模板

itemSchema需要 2.5.2 及以上版本。它支持 HTML 字符串或 SchemaNode 两种形式，用来统一控制映射命中后的渲染方式：

• 映射值是非 object时，模板里用${item}获取映射值；
• 映射值是object时，用模板语法${xxx}获取该 object 的属性值；
• 模板中还可以用${xxx}获取数据域中的其他变量。

HTML 或字符串模板

{ "type": "page", "body": { "type": "mapping", "value": "1", "map": { "1": "第一", "2": "第二", "3": "第三", "*": "其他" }, "itemSchema": "自定义模板：<span style='color: red'>${item}</span>" } }

这里映射值是字符串，${item}取到的就是map中命中的文本。

SchemaNode 模板

{ "type": "page", "body": { "type": "mapping", "value": "1", "map": { "1": "第一", "2": "第二", "3": "第三", "*": "其他" }, "itemSchema": { "type": "tag", "label": "${item}" } } }

在模板中引用 object 属性与数据域变量

当映射值是 object 时，模板可直接取 object 属性，也可以取数据域变量。下面page的data里提供了myName，map的 value 是 object，itemSchema同时用到了两者：

{ "type": "page", "data": { "myName": "cat" }, "body": { "type": "mapping", "value": "1", "map": { "1": { "label": "开心", "color": "red" }, "2": { "label": "伤心", "color": "blue" }, "3": { "label": "冷漠", "color": "gray" }, "*": "其他" }, "itemSchema": { "type": "tag", "label": "${myName} ${label}", "color": "${color}" } } }

value命中"1"后，${label}、${color}取自 object 的label、color属性，${myName}取自数据域。

value 为数组时映射展示多个

1.5.0 及以上版本，value是数组时会逐项映射、展示多个结果：

{ "type": "page", "body": { "type": "mapping", "value": ["1", "2", "3", "4", "5"], "map": { "1": "<span class='label label-info'>漂亮</span>", "2": "<span class='label label-success'>开心</span>", "3": "<span class='label label-danger'>惊吓</span>", "4": "<span class='label label-warning'>紧张</span>", "*": "<span class='label label-default'>其他</span>" } } }

"5"没有对应 key，落到*展示「其他」。

用对象数组作为 map 映射源

2.5.2 起，map除了 k-v 对象还支持对象数组。

简单对象数组

{ "type": "mapping", "value": "1", "map": [{"1": "第一"}, {"2": "第二"}, {"3": "第三"}, {"*": "其他"}] }

多 key 对象数组

当每个映射项有多个 key 时，需要用valueField指定哪个字段作为匹配value的 key（不配置时默认用value），可以用labelField指定展示字段（默认label）：

{ "type": "mapping", "value": "happy", "valueField": "name", "map": [ { "name": "happy", "label": "开心" }, { "name": "sad", "label": "悲伤" }, { "name": "*", "label": "其他" } ] }

注意：配置labelField后，映射值无法再作为 schema 组件渲染，和itemSchema的限制一样。完整示例（显式指定labelField）：

{ "type": "page", "body": { "type": "mapping", "value": "happy", "valueField": "name", "labelField": "label", "map": [ { "name": "happy", "label": "开心", "color": "red" }, { "name": "sad", "label": "悲伤", "color": "blue" }, { "name": "*", "label": "其他", "color": "gray" } ] } }

用作 Field：Table 列、List、Card 和表单静态展示

当 mapping 用在 Table 的列配置 Column、List 的内容、Card 卡片的内容和表单的 Static-XXX 中时，可以设置name属性，映射同名变量，不再需要手动写value。

Table 列示例，每行的type字段值自动参与映射：

{ "type": "table", "data": { "items": [ { "id": "1", "type": "1" }, { "id": "2", "type": "2" }, { "id": "3", "type": "3" } ] }, "columns": [ { "name": "id", "label": "Id" }, { "name": "type", "label": "映射", "type": "mapping", "map": { "1": "<span class='label label-info'>漂亮</span>", "2": "<span class='label label-success'>开心</span>", "3": "<span class='label label-danger'>惊吓</span>", "4": "<span class='label label-warning'>紧张</span>", "*": "其他：${type}" } } ] }

List 的内容、Card 卡片的内容配置同上。

表单中静态展示用static-mapping：

{ "type": "form", "data": { "type": "2" }, "body": [ { "type": "static-mapping", "name": "type", "label": "映射", "map": { "1": "<span class='label label-info'>漂亮</span>", "2": "<span class='label label-success'>开心</span>", "3": "<span class='label label-danger'>惊吓</span>", "4": "<span class='label label-warning'>紧张</span>", "*": "其他：${type}" } } ] }

布尔值字段也支持映射，key 可以用"1"/"0"，也可以用"true"/"false"：

{ "type": "form", "data": { "type": true }, "body": [ { "type": "static-mapping", "name": "type", "label": "映射", "map": { "true": "<span class='label label-info'>开</span>", "false": "<span class='label label-default'>关</span>" } } ] }

远程拉取字典与关联上下文变量

1.1.6 起可以配置source，不写死map而由接口或变量提供字典，数据格式参考map配置。

远程接口

{ "type": "form", "data": { "type": "2" }, "body": [ { "type": "mapping", "name": "type", "label": "映射", "source": "/api/mapping" } ] }

默认source有 30s 缓存，适合通常不常变更的字典数据。想改缓存时间，参考 API 类型 文档中的cache配置（单位毫秒）。

关联上下文变量

source也可以取数据域变量而不是发请求。示例中initApi的响应处理把接口返回的整个data字段存入zidian变量（$$$$是整体赋值的写法），mapping 通过$${zidian}引用它：

注意：当数据域里的变量值为$$时，表示将所有接口返回的data字段值整体赋值到对应的 key 中

{ "type": "form", "initApi": { "url": "/api/mapping", "method": "get", "responseData": { "zidian": "$$$$", "type": "2" } }, "body": [ { "type": "mapping", "name": "type", "label": "映射", "source": "$${zidian}" } ] }

验证渲染是否符合预期

• 调整value（或 Field 模式下行数据的同名字段）为map中已配置的 key，确认页面展示对应的文本/HTML/组件；
• 把value改成map中不存在的值，确认落到*兜底项；
• 数据不存在的场景确认展示placeholder配置的文本；
• 用了itemSchema后，确认展示的是模板渲染结果（${item}或 object 属性替换后），而不是映射值本身。

属性与版本限制

Mapping 映射 的属性表：

版本要求汇总：

• value为数组映射展示多个：1.5.0 及以上；
• source远程字典 / 上下文变量：1.1.6 及以上；
• itemSchema、对象数组map、valueField/labelField：2.5.2 及以上。

两个最容易踩的限制：一是配置了itemSchema后映射值不再作为 schema 渲染；二是配置了labelField（对象数组场景）后同样失去 schema 渲染能力。需要「命中后渲染整块组件」且同时想加包装样式时，把包装组件直接写进map的 value（第三节的写法），而不是叠加itemSchema。

【免费下载链接】amis前端低代码框架，通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis