fix-xml-native-html

Name: fix-xml-native-html
Author: ui5

github.com/ui5开发44141 次安装1 周前更新

代码仓库

关于 fix-xml-native-html

面向 UI5 开发者的技能，用于处理 XML 视图或片段中原生 HTML 和 SVG 引发的检查问题。它将标记映射为 UI5 控件，并为图形提供图标或自定义控件方案。

主要功能

01将 HTML 元素映射为 UI5 控件
02用 UI5 图标替换 SVG 图标
03提供复杂 HTML 布局建议
04将经过净化的 HTML 作为最后方案

适用场景

01修复 XML 视图中过时的 HTML
02替换检查器标记的内嵌 SVG 图标
03现代化布局并保持视觉效果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ui5/plugins-coding-agents --skill fix-xml-native-html

安装后在 Claude Code 中输入/fix-xml-native-html确认已加载。

详细介绍

修复 XML 视图/片段中的原生 HTML 和 SVG

此技能用于修复 XML 视图/片段中由 UI5 检查器检测到、但无法自动修复的原生 HTML 和 SVG 用法，因为这些问题需要了解适当的 UI5 控件替代方案。

处理的检查器规则

规则 ID	消息模式	此技能的操作
`no-deprecated-api`	在 XML 视图/片段中使用原生 HTML 已弃用	替换为 UI5 控件
`no-deprecated-api`	在 XML 视图或片段中弃用使用 SVG	替换为 UI5 图标或自定义控件

适用场景

看到如下检查器输出时，请应用此技能：

MyView.view.xml:15:5 error Usage of native HTML in XML Views/Fragments is deprecated  no-deprecated-api
MyView.view.xml:25:5 error Deprecated use of SVG in XML View or Fragment  no-deprecated-api

运行 npx @ui5/linter --details，获取有关弃用原生 HTML 的文档链接。

背景：弃用原生 HTML/SVG 的原因

以前可以通过 sap.ui.core.HTML 控件和 html 命名空间在 XML 视图中使用原生 HTML。不过，这种做法：

绕过 UI5 的控件生命周期和渲染机制
无法集成 UI5 主题
可能导致无障碍访问问题
与现代 UI5 严格模式不兼容

修复策略

1. 原生 HTML 元素 → UI5 控件

问题：通过 html: 命名空间使用 HTML 元素。


<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m"
    xmlns:html="http://www.w3.org/1999/xhtml">
    <html:div class="myContainer">
        <html:span>Some text</html:span>
        <html:a href="https://example.com">Link</html:a>
        <html:img src="image.png" alt="My Image" />
    </html:div>
</mvc:View>

修复策略：替换为等效的 UI5 控件。


<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m">
    <VBox class="myContainer">
        <Text text="Some text" />
        <Link text="Link" href="https://example.com" />
        <Image src="image.png" alt="My Image" />
    </VBox>
</mvc:View>

HTML 到 UI5 控件的映射

HTML 元素	UI5 控件	备注
`<html:div>`	`<VBox>`、`<HBox>`、`<FlexBox>`	垂直布局使用 VBox，水平布局使用 HBox
`<html:span>`	`<Text>`、`<Label>`	显示文本使用 Text，表单标签使用 Label
`<html:p>`	`<Text>`	段落之间可在文本中使用 `\n`
`<html:a>`	`<Link>`	支持完整链接功能，包括 href
`<html:img>`	`<Image>`	支持 src、alt、width、height
`<html:input>`	`<Input>`、`<SearchField>`	提供多种输入类型
`<html:button>`	`<Button>`	完整的按钮功能，支持图标
`<html:ul>` / `<html:li>`	`<List>` / `<StandardListItem>`	也可使用包含条目的 `<VBox>`
`<html:ol>`	包含 `<ObjectListItem>` 的 `<List>`	使用自定义编号
`<html:table>`	`<Table>`（sap.m）	对于大型数据，也可使用 `<sap.ui.table.Table>`
`<html:h1>` - `<html:h6>`	`<Title>`	使用 `level` 属性设置标题级别
`<html:br>`	（无）	在 Text 中使用 `\n`，或使用单独的控件
`<html:hr>`	包含 `<ToolbarSpacer>` 的 `<Toolbar>`	也可使用自定义样式
`<html:iframe>`	`<HTML>` 控件	仅在绝对必要时使用
`<html:form>`	（直接使用表单控件）	UI5 以不同方式处理表单提交
`<html:select>`	`<Select>`、`<ComboBox>`	提供完整的下拉菜单功能
`<html:textarea>`	`<TextArea>`	多行输入

2. 复杂 HTML 结构

问题：使用嵌套 HTML 实现布局。


<html:div class="header">
    <html:div class="logo">
        <html:img src="logo.png" />
    </html:div>
    <html:div class="nav">
        <html:a href="#home">Home</html:a>
        <html:a href="#about">About</html:a>
    </html:div>
</html:div>

修复策略：使用 UI5 布局控件。


<HBox class="header" alignItems="Center" justifyContent="SpaceBetween">
    <Image src="logo.png" class="logo" />
    <HBox class="nav">
        <Link text="Home" href="#home" class="sapUiSmallMarginEnd" />
        <Link text="About" href="#about" />
    </HBox>
</HBox>

3. SVG 图形 → UI5 图标或自定义控件

问题：在 XML 视图中直接使用 SVG。


<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m"
    xmlns:svg="http://www.w3.org/2000/svg">
    <svg:svg width="100" height="100">
        <svg:circle cx="50" cy="50" r="40" fill="blue" />
    </svg:svg>
</mvc:View>

修复策略 A - 用于图标：使用带有图标字体的 UI5 Icon 控件。


<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m"
    xmlns:core="sap.ui.core">
    <core:Icon src="sap-icon://circle-task" size="2rem" color="blue" />
</mvc:View>

修复策略 B - 用于复杂图形：创建自定义控件或使用 HTML 控件。

// CustomGraphic.js - for complex SVG that can't be replaced with icons
sap.ui.define([
    "sap/ui/core/Control"
], function(Control) {
    "use strict";

    return Control.extend("my.app.control.CustomGraphic", {
        metadata: {
            properties: {
                color: { type: "string", defaultValue: "blue" }
            }
        },

        renderer: {
            apiVersion: 2,
            render: function(oRm, oControl) {
                oRm.openStart("svg", oControl);
                oRm.attr("width", "100");
                oRm.attr("height", "100");
                oRm.openEnd();

                oRm.openStart("circle");
                oRm.attr("cx", "50");
                oRm.attr("cy", "50");
                oRm.attr("r", "40");
                oRm.attr("fill", oControl.getColor());
                oRm.openEnd();
                oRm.close("circle");

                oRm.close("svg");
            }
        }
    });
});


<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m"
    xmlns:custom="my.app.control">
    <custom:CustomGraphic color="blue" />
</mvc:View>

4. 常见图标替代项

替换 SVG 图标时，请使用 SAP 图标字体：

SVG 模式	UI5 图标
对勾/勾号	`sap-icon://accept`
叉号/X	`sap-icon://decline`
圆形	`sap-icon://circle-task`
右箭头	`sap-icon://navigation-right-arrow`
左箭头	`sap-icon://navigation-left-arrow`
加号/添加	`sap-icon://add`
减号/移除	`sap-icon://less`
编辑/铅笔	`sap-icon://edit`
删除/垃圾桶	`sap-icon://delete`
搜索	`sap-icon://search`
设置/齿轮	`sap-icon://settings`
用户/人物	`sap-icon://person-placeholder`
日历	`sap-icon://calendar`
下载	`sap-icon://download`
上传	`sap-icon://upload`

浏览所有可用图标：UI5 图标浏览器

5. 必须保留的 HTML 内容

对于绝对需要 HTML 的情况（例如，渲染外部 HTML 内容）：


<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m"
    xmlns:core="sap.ui.core">
    <core:HTML content="{/sanitizedHtmlContent}" sanitizeContent="true" />
</mvc:View>

警告：仅在内容符合以下条件时使用：

无法通过 UI5 控件实现
已经过适当的清理
来自可信来源

6. 样式注意事项

从 HTML 迁移到 UI5 控件时：

CSS 类：通过 class 属性应用自定义类
```
<VBox class="myCustomContainer">
```

内联样式：使用 customData 设置 CSS 变量，或使用 layoutData 聚合

<VBox>
    <layoutData>
        <FlexItemData growFactor="1" />
    </layoutData>
</VBox>

主题：UI5 控件会自动适配所选主题（Horizon、Quartz 等）

实施步骤

在 linter 输出中识别 HTML/SVG 的用法
确定每个 HTML 元素的用途：
- 布局容器 → 使用 VBox、HBox、FlexBox
- 文本内容 → 使用 Text、Label、Title
- 交互元素 → 使用 Button、Link、Input
- 图片 → 使用 Image
- 图标 → 使用 sap.ui.core.Icon
检查可能需要更新的自定义 CSS
将元素替换为对应的 UI5 控件
替换完所有 HTML 元素后，移除 xmlns:html 命名空间
测试布局，确保视觉效果一致

修复示例

给定以下 linter 输出：

MyView.view.xml:5:3 error Usage of native HTML in XML Views/Fragments is deprecated  no-deprecated-api
MyView.view.xml:12:5 error Deprecated use of SVG in XML View or Fragment  no-deprecated-api

修改前：

<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m"
    xmlns:html="http://www.w3.org/1999/xhtml"
    xmlns:svg="http://www.w3.org/2000/svg">
    <html:div class="card">
        <html:div class="cardHeader">
            <svg:svg width="24" height="24">
                <svg:circle cx="12" cy="12" r="10" fill="green" />
            </svg:svg>
            <html:span class="title">Status: Active</html:span>
        </html:div>
        <html:p>This is the card content.</html:p>
        <html:a href="https://example.com">Learn more</html:a>
    </html:div>
</mvc:View>

修改后：

<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m"
    xmlns:core="sap.ui.core">
    <VBox class="card">
        <HBox class="cardHeader" alignItems="Center">
            <core:Icon src="sap-icon://status-positive" color="green" class="sapUiSmallMarginEnd" />
            <Text text="Status: Active" class="title" />
        </HBox>
        <Text text="This is the card content." />
        <Link text="Learn more" href="https://example.com" />
    </VBox>
</mvc:View>

注意事项

UI5 控件与主题、无障碍功能和响应式设计的集成效果更好
完成现代化改造后，应彻底移除 html: 命名空间
对于复杂 HTML（如嵌入式 iframe），可以将 sap.ui.core.HTML 控件作为最后手段，并设置 sanitizeContent="true"
为了更好地支持主题，尽可能用 UI5 图标字体替换 SVG 图标
可考虑使用 sap.m.FormattedText 实现类似 HTML 的富文本格式
对于复杂的图形需求，自定义控件能提供最大的控制能力

基本信息

作者: ui5
仓库: ui5/plugins-coding-agents
分类: 开发
安装次数: 141
GitHub Stars: 44

报告问题

fix-xml-native-html

关于 fix-xml-native-html

主要功能

适用场景

安装

详细介绍

修复 XML 视图/片段中的原生 HTML 和 SVG

处理的检查器规则

适用场景

背景：弃用原生 HTML/SVG 的原因

修复策略

1. 原生 HTML 元素 → UI5 控件

HTML 到 UI5 控件的映射

2. 复杂 HTML 结构

3. SVG 图形 → UI5 图标或自定义控件

4. 常见图标替代项

5. 必须保留的 HTML 内容

6. 样式注意事项

实施步骤

修复示例

注意事项

相关技能

评论