# @abap2ui5/embed-control 中文文档

规范地址：https://npmcn.com/package/%40abap2ui5/embed-control/

版本：0\.3\.0
npm 元数据更新时间：2026-10-14T07:31:01.227Z
中文译文更新时间：2026-11-06T23:09:13.462Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40abap2ui5/embed-control
原文对照：https://npmcn.com/package/%40abap2ui5/embed-control/?lang=original
项目主页：https://github.com/abap2UI5/embed-control/tree/main/packages/embed-control#readme
源码仓库：https://github.com/abap2UI5/embed-control

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：57.6 kB，7 个文件
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-09-29T00:20:02.789Z
- 最新版本发布：2026-10-14T07:31:00.730Z
- 近 30 天下载量：2188（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

在任何 UI5 应用中嵌入 abap2UI5 应用: 一个运行执行 z2ui5 if app 的 ABAP 类的 UI5 控制

## 安装

```sh
npm install @abap2ui5/embed-control
```

也可以使用：`pnpm add @abap2ui5/embed-control`、`yarn add @abap2ui5/embed-control`、`bun add @abap2ui5/embed-control`

## README

# @abap2ui5/嵌入式控制

运行 [abap2UI5 (中文(简体) )](https://github.com/abap2UI5/abap2UI5) 应用程序在任何UI5应用程序内.

abap2UI5 纯在ABAP中构建 UI5 应用程序: 实施 ABAP 类 `z2ui5_if_app` 决定视图并处理所有事件。 这个包裹 此应用程序进入 **** UI5 应用作为普通控件, 在您自己的旁边 控件 :

```xml
<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns:z2ui5="z2ui5.embed">
  <z2ui5:Container app="Z2UI5_CL_UI5_APP_HI_WORLD" height="400px"/>
</mvc:View>
```

包裹是控制,没有别的。 Abap2UI5 前端它包装 由ABAP2UI5安装的应用程序对讲机产生,所以它总是有 版本的后端, 你的应用程序从来没有携带它的副本.

## 安装

```bash
npm install @abap2ui5/embed-control
```

然后两个条目 在你的应用程序. `ui5.yaml` - 这样 `ui5 build` 复制控件 输入您的应用程序`ui5 serve` 服务它反正:

```yaml
builder:
  settings:
    includeDependency:
      - "@abap2ui5/embed-control"
```

`manifest.json` - 控件的命名空间:

```json
"sap.ui5": {
  "resourceRoots": { "z2ui5.embed": "./thirdparty/z2ui5/embed/" }
}
```

这栋楼把它投入 `dist/thirdparty/z2ui5/embed/` 和你的部署 把它和应用程序的其他文件一样。 未下关 `resources/`页:1 部署到ABAP系统的应用程序回答每个问题 `<app>/resources/` 从路径 UI5系统库. 相对资源根是独立的 在SAP Fiori的发射板上.

没有其他任何设备部署在任何地方:控制器是一个平板模块(否) 组件,没有库),所以没有涉及ABAP系统的应用索引条目, 而任何数量的应用程序都可以携带自己的副本.

## 使用

在 XML 视图中,如上或代码中:

```js
sap.ui.require(["z2ui5/embed/Container"], (Container) => {
  new Container({
    app: "ZCL_MY_ABAP2UI5_APP",
    params: { customer: "4711" },
    height: "600px",
  }).placeAt("content");
});
```

| 财产 | 类型 | 默认 |  |
| --- | --- | --- | --- |
| `app` | 字符串 |  | ABAP课要跑. 空的时候没有开始 |
| `endpoint` | 字符串 | `/sap/bc/z2ui5` | 此服务器上的 abap2UI5 HTTP 服务路径 - 绝对, 或相对于页面地址( a) `<base>` 没有查询或片段。 前端被从中装入,圆通去取. 见 [后端](https://npmcn.com/package/%40abap2ui5/embed-control/#readme-backend) |
| `params` | 对象 |  | `{ name: "value" }`,由应用程序读取 `client->get( )-t_comp_params`· ; `{ name: ["a", "b"] }` 在一个名称下将数个值交接。 一个值是 `null` 或者说 `undefined` 被忽略; 一个对象作为 JSON 文本被移交 |
| `ownsPage` | 布尔 | `false` | 将页面交给应用程序 -- -- 用于此控件的一页,而不是其他的:该应用程序在自己的一页上有它拥有的东西 -- -- URL散列(hash路由, `set_push_state`, (中文(简体) ), `hash_replace`,浏览器在路由应用程序之间回向和前进,重新加载时恢复的路由,文档标题和favicon,环行旅行期间的全局繁忙指示器,浏览器的"leave page?"提示未保存的更改. Off,他们是你的应用程序:嵌入式应用程序留下标题,favicon和散列,忙于自己的区域,没有引起快感. 当您的页面拥有比控件更强的功能时——一个Fiori元素对象页面,就把它放下. 每页一个这样的控制。 一个变化开始新的应用程序, 像其中之一 `app`, (中文(简体) ), `endpoint` 或者说 `params`需要abap2UI5 1.147.0,读取它(控制卡) `ownsHash` 以它发誓,一个年长的人忽视它 |
| `ownsHash` | 布尔 | `false` | 更古老、更狭窄的名字 `ownsPage`:将网页的 URL 散列交给应用 - 对于一个是这个控制而不是其他的页面, 没有任何路径: 应用然后像它自己的一页(hash路由, `set_push_state`, (中文(简体) ), `hash_replace`,浏览器返回并转发到路由应用程序之间,重新装入时恢复的路由). 当您的应用路线通过散列时, 离开它 - 一个 Fiori 元素对象页面。 每页一个这样的控制。 一个变化开始新的应用程序, 像其中之一 `app`, (中文(简体) ), `endpoint` 或者说 `params`。需要abap2UI5 1.147.0, 将整个页面交给它, 至于 `ownsPage`;一个更年长的人忽略它 |
| `width` | CSSS 大小 | `100%` |  |
| `height` | CSSS 大小 | `100%` | 应用程序装满了容器 - 给它一个高度, 或有一个母程序。 更改 `width` 或者说 `height` 更改所在区域大小; 运行中的应用程序没有重新启用 |

| 活动 | 参数 |  |
| --- | --- | --- |
| `componentCreated` | `component` | 该应用的组件存在( 第一次回合正在进行) |
| `componentFailed` | `reason` | 无法创建 - 端点不是此服务器上的路径, 前端无法装入, 或者组件失败 |

| 方法 |  |
| --- | --- |
| `restart()` | 结束运行的会话, 并用当前启动应用程序 `app`, (中文(简体) ), `endpoint` 财务报告和审定财务报表 `params` - 应用程序从头开始,或者在后面再试一次 `componentFailed` |

每个控制是它的 **拥有 abap2UI5 会话** - 两个控制器是相同的 类不共享状态。 变化 `app`, (中文(简体) ), `endpoint` 或者说 `params` 结束 运行会话并开始新的会话; `restart()` 将同样与 值; 破坏控件也会结束它。 三个都是 普通的属性,所以它们可以 绑在你的模型 - `params` 实值 与运行中的应用程序的起始值进行比较,所以绑定 在新对象中交接相同的参数时,不会重新启动 应用程序,以及 `endpoint` 在另一个拼法中命名同一地点(a) 沿着斜线走,一条相对的路径)也一样.

两起事件都是同步发生的 在开始的渲染之后 app - 包含一个被拒绝的终点 。 失败的开始不重复 本身:更改三个属性之一,或调用 `restart()`。一个 隐形控件( n)`visible="false"`开始到显示为止;a 运行的应用程序随状态而运行,而其控制却被隐藏.

## 实例

使用软件包的完整示例 [abap2UI5/样品-嵌入式控制](https://github.com/abap2UI5/samples-embed-control), (中文(简体) ), 分会 `standard`,所有的包 从npm:

-   `freestyle/` - 一个UI5自由式的应用程序,有三个控制器,同样作为BSP `Z2UI5_HOST` 尝试在系统上用平地取出
-   `fiori-elements/` - 菲奥里元素应用软件,控制在 **自定义 其对象页面的章节**: abap2UI5 应用程序获得对象的密钥 作为参数的页面
-   `fiori-elements-v2/` - Fiori元素应用程序 **奥达塔V2** 与 控制在一个 **对象页面扩展名**,则 **RAP服务** 其内容为:; 在树枝上 `rap`所有这一切都是为了一个abapGit拉上一个带有RAP的系统
-   `card/` - 一个 **UI 整合卡** sAP 构建工作区,运行任何 abap2UI5 app:类为卡参数,后端为卡 目标

它的README走过包裹被接通的地方.

## 后端

应用在ABAP系统上运行 [abap2UI5 已安装](https://abap2ui5.github.io/docs/configuration/installation.html) 及其 HTTP 服务(默认) `/sap/bc/z2ui5`)活动. 控制需求 **abap2UI5 1.145.0或以后**,其服务答案 `?z2ui5-bundle` - 进 节点是 `@abap2ui5/node-runtime` 1.145.0, 联合呼吁程序 `@cap2ui5/cds-plugin` 0.3.1, 运行在它上:

```
GET  /sap/bc/z2ui5?z2ui5-bundle   the frontend as one script - loaded once per page
POST /sap/bc/z2ui5                the roundtrips, one session per control
GET  /sap/bc/z2ui5                abap2UI5's own page, unchanged
```

更古老的 abap2UI5 答案及其页面; 控件再起火 `componentFailed` ("没有abap2UI5前端在.")而不是开始.

**1.145.0还没有这样做.** abap2UI5 1.146.0 修复所有这些 1.145.0 自行计划:

-   **URL散列是前端的.** 1.145.0 清理东道主的散列物 第一次回合和每次回合之后: Fiori 元素对象页返回 sAP Building Work Zone 在其列表中留下一张卡片。 还有 主机散列形状像abap2UI5自己的深层链接, `#/app/<CLASS>`,获胜 页:1 `app` 属性 - 该类开始代替。 路途经过 hash - 一个 Fiori 元素应用程序, 一个带有 UI5 路由器的应用程序, SAP Build Work 区 - 需要1.146.0或以后, 谁的前端知道它是 嵌入并留给您的应用( abap2UI5 677e71b, #2808) .
-   **没有CSRF标志性的握手.** SAP approuter 路由检查 CSRF 令牌 默认( e)`cds add approuter` 生成这样的路径)和 1.145.0 发送 无 - 每一次往返都以403"X-CSRF-Token: request"拒绝. 给 服务路线 `"csrfProtection": false`; abap2UI5 的自产地 检查保持原地。 1.146.0 获取该标志 403 (bap2UI5 #2802) (英语).

每一次释放都要通过ABAP2UI5主体和1.145.0测试 (单位:千美元)`@abap2ui5/node-runtime` 1.145.0) - 没有需要的散列. 这个 软件包记录其 `package.json` (单位:千美元)`abap2ui5.minBackend`),以及 这是测试安装的版本.

**页面和服务必须共享一个来源.** abap2UI5 拒绝 a 后谁 `Origin` 指定另一个主机而不是它自己的(其CSRF防御),以及 控制只从此服务器上的路径装入前端 - a `endpoint` 解决另一个来源 被拒绝,因为会发生什么 后面是您页面中运行的代码。 所以浏览器通过您到达服务 app的出处 :

-   **已部署** - 应用软件来自同一系统(BSP、发射板)或 approuter / 目的地路线 `/sap/bc/z2ui5` 对它
-   **`ui5 serve`** - 代理中件转发 `/sap` 对系统,像 `ui5-middleware-simpleproxy` 输入 [实例](https://github.com/abap2UI5/samples-embed-control/tree/main/freestyle)。 。 。 . 它重写 `Host` 并告诉后端 dev 服务器的主机在 `X-Forwarded-Host`,该ABap2UI5比较了浏览器的 `Origin` 与 (默认受托; `check_trust_forwarded_host` 在用户退出时)

**内容-安全政策:** 前端是一个 `<script src>` 属于自己的 源代码,其中每个模块都是函数 - 没有从一个函数中评估 绳子。 一个主机 `script-src 'self'` 没有 `'unsafe-eval'` 不需要任何东西 额外(UI5 1.71) `'unsafe-eval'`) (中文(简体) ).

## UI5 库

嵌入式应用程序加载了 UI5 库中的 ABAP 视图名称 。 与UI5 服务于框架的CLI(`framework:` 内 `ui5.yaml`),列出每个库 您的ABAP应用软件使用那里, 不仅仅是您自己观点使用的 - 你好 例如,世界应用需要 `sap.ui.layout` - 还有 `sap.ui.codeeditor`, (中文(简体) ), abap2UI5的开发工具(嵌入式app中的Ctrl+F12)需要. A 类 在浏览器控制台中缺少包含脚本的库失败 出错; 部署到一个系统的应用程序拥有这个系统的每一个库.

## 支持的UI5版本

与abap2UI5同层: OpenUI5 / SAPUI5 **1.71 联合国** 及后会. 这个 自由式实例在1.71和1.136上测试,Fiori元素实例 用于SAPUI5 1.136上的OData V4和V2,OpenUI5 1.136上的卡.

您的应用程序工具: UI5 CLI 3 或 4 - 该软件包 `ui5.yaml` 实值 specVersion 3.0,每个发行都与两者相建.

## 已知的限制

-   **每页前端一个**: 第一个开始的控件决定 前端的端点来自; 每个控件仍然发送其圆通 到它的终点。 和别人分享负载的控制器 自己的终点,并看到它失败,尝试过自己的终点一次. A 类 捆绑装入主机本身 - a `<script src="<endpoint>?z2ui5-bundle">` 它的一页,使其温暖 - 是照原样,不再加载.
-   **主页的移动设置,有abap2UI5 1.146.0及更早.** `sap.m.App`,嵌入式前端的根,运行 UI5 的 `sap/ui/util/Mobile.init` 当它被创建时——每页一次,使用 设置谁先称呼它。 在主机页面上没有 `sap.m.App` 它本身,使 `height: 100%` 打开 `<html>`,添加视图元标记 用于禁用缩放和格式检测元标记,并在 iOS turn 上 本地滚动关闭( n)`position: fixed` 打开 `<html>`并隐藏 浏览器的UI. abap2UI5 1.147.0先打电话, 所有东西都关了,所以主机保持它的页面;什么留在电话上,或者 平板电脑是可网络应用元标记 `sap.m.App` 设定于每 翻译。 嵌入式应用程序根部的1.14.7.0是一个 `sap.m.NavContainer`,没有设置 `ownsPage` 根为 页:1 `sap.m.App` 再说一遍,在应用程序的一页。 主持人 `sap.m.App` 它本身在任何释放时都不受影响.
-   **从兄弟会BSP自定义控制 `z2ui5_cci` 编号 : `z2ui5_ccc`** (bap2UI5-addons/海关控制,客户自己的图书馆) 将系统置于自身前缀下的代理 - SAP 构建工作 Zone 目的代理, 带有前缀的 approuter 路由 - 需要 abap2UI5 1.147.0 (英语). 在那之前,捆绑者会命名他们的路径 因为系统有他们, `/sap/bc/ui5_ui5/sap/z2ui5_cci`,这是东道主的 源代码没有;从那时起,在其捆绑的名称上它就是节点 请在下面,前端放上控件的前缀 `endpoint` 于诸根前. 控制器里没有什么变化.
-   abap2UI5的构建是为了拥有整个页面. 它的嵌入模式离开 您的应用程序的 URL( 自1.14. 6. 0 起) - 除非 `ownsHash` 手握散块 背书(从1.14.7.0起) -- -- 和从1.14.7.0起还从文档 标题、 favicon 、 繁忙指示器和“ 离开页面” 。 提示 好吧,除非 `ownsPage` 将页面递回;在那之前有一个嵌入式应用程序 在回合中显示全局繁忙指标,并可能设置 当ABAP应用程序要求时,文档标题和favicon。 其余的就是 临璶ㄓ (单位:千美元)[积压项目](https://github.com/abap2UI5/abap2UI5/blob/main/backlog/items/embed-as-reuse-component.md)) (中文(简体) ). 最多1.146.0个嵌入式应用使其根成为 `sap.m.App`,则 全屏根:主题本身的背景和高度 百分百在每一个祖先 直到控制区。 从1.147.0起 这是一个 `sap.m.NavContainer` 仅填充区域,除非 `ownsPage` 把页面拿回来。 在1.146.0之前,该应用程序还采用 当它开始时,从应用程序中的任何位置聚焦 - 根聚焦 中的第一个字段,并且ABAP app 可将焦点设定为 不错.
-   **嵌入式前端的全页行为.** 它的错误对话框 "重新开始" - 和"重新开始" 在其致命错误屏幕上 - 重新装入整个 页面,包含您的应用程序。 它的开发者工具包扎 `window.console` 应用程序运行时的方法(浏览器控制台继续工作;其源 链接指向包件),并在文档上收听 Ctrl+F12.
-   **持住活计.** 嵌入式应用程序组件属于您的应用程序 组件, 控件的所有者和 abap2UI5 前端不 支持 保持活性:一个宣布它的应用程序( )`sap.ui5/keepAlive`, UI5 数据 1.88+)报告它有一个嵌入式应用程序时没有保存-活性支持,如UI5 对每个没有它的嵌入组件.

## 里面的东西

| 路径 |  |
| --- | --- |
| `src/Container.js` | 控制系统, `z2ui5.embed.Container` |
| `src/Container.css` | 它的样式表, 由控件加载 |
| `ui5.yaml` | 服务 `src/` 下级 `/thirdparty/z2ui5/embed/` |
| `CHANGELOG.md` | 每一次发布 |

## 许可证

麻省理工学院

## 常见问题

### @abap2ui5/embed-control 是什么？

在任何 UI5 应用中嵌入 abap2UI5 应用: 一个运行执行 z2ui5 if app 的 ABAP 类的 UI5 控制

### 如何安装 @abap2ui5/embed-control？

在项目目录运行 npm install @abap2ui5/embed-control，或使用 pnpm add / yarn add / bun add。

### @abap2ui5/embed-control 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/abap2ui5\_\_embed-control 是否存在。

### @abap2ui5/embed-control 可以商用吗？

@abap2ui5/embed-control 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @abap2ui5/embed-control 的下载量有多少？

根据 npm 官方下载统计，@abap2ui5/embed-control 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,188 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @abap2ui5/embed-control 还在维护吗？

最新版本 0\.3\.0 发布于 2026/10/14（24 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/09/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。