# @betterportal/theme-runtime 中文文档

规范地址：https://npmcn.com/package/%40betterportal/theme-runtime/

版本：11\.0\.9
npm 元数据更新时间：2026-11-07T08:30:06.508Z
中文译文更新时间：2026-11-08T03:10:57.472Z
软件包许可：\(AGPL-3\.0-only OR Commercial\)

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

原始 npm 页面：https://www.npmjs.com/package/%40betterportal/theme-runtime
原文对照：https://npmcn.com/package/%40betterportal/theme-runtime/?lang=original
项目主页：https://github.com/BetterCorp/BetterPortal#readme
源码仓库：https://github.com/BetterCorp/BetterPortal

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

- 包体积（解压后）：335 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-07-30T23:32:48.714Z
- 最新版本发布：2026-11-07T08:30:06.160Z
- 近 30 天下载量：1924（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：85（近 12 个月 85 个）

## 中文简介

主题包的后端组装更好的门户网站浏览器运行时间

## 安装

```sh
npm install @betterportal/theme-runtime
```

也可以使用：`pnpm add @betterportal/theme-runtime`、`yarn add @betterportal/theme-runtime`、`bun add @betterportal/theme-runtime`

## README

# @ betterportal/ 主题运行时间

共享后端和浏览器- shell 运行时间为 BetterPortal 节点外壳包.

软件包在此顺序下组装后端的一个JavaScript资产:

1.  安装的 HTMX 核心 `htmx.org` 软件包.
2.  外壳的打出演示文稿适配器.
3.  更好的门户 `bp-shell` 运行时间.
4.  捆绑的HTMX SSE扩展.

浏览器从不动态地发现或加载扩展. 所需资产由后端解决,而缺失资产则失败捆绑创建.

外壳适配器作为 TSX 编写 `jsx-htmx`是因为 `js()` 帮助者 :

```tsx
/** @jsxImportSource jsx-htmx */
import { js } from "jsx-htmx";
import {
  buildBetterPortalShellRuntimeAsset,
  type BetterPortalShellAdapter
} from "@betterportal/theme-runtime";

const adapterSource = js(() => {
  window.BetterPortalShellAdapter = {
    setLoading(loading, outlet) {
      outlet?.toggleAttribute("data-bp-loading", loading);
    }
  } satisfies BetterPortalShellAdapter;
});

const asset = await buildBetterPortalShellRuntimeAsset({
  adapterSource
});
```

`js()` 返回安全 `RawText`。直接传递给运行时的构建者,或者直接将其放入一个 `<script>` 键。 不要打电话 `.toString()` 而不把它包起来 `raw()`。 。 。 .

共享运行时间拥有服务/应用 URL 重写,管理 BP 头头,头觉预装,HTMX 生命周期处理,下载,历史,认证失败,SSE, `bp-route` 和途径铬州。 它从未在浏览器中发现服务计划.

所管理的BP头只被发送到HTTPS上注册的应用服务源. 本地开发可在 `localhost`, (中文(简体) ), `127.0.0.1`,或 `[::1]`;其他HTTP服务URL必须迁移到HTTPS. Shells 发布启用的路由、槽、碎片、 认证和 shell 绑定的出处 。 仍然支持基于遗产来源的抬头所有权和范围.

预加载是推测性的:不包含已禁用控件和所配置的认证源,不遵循HTTP重定向,并等待响应指令/UI更改以被明确激活. 重写链接保留租户 URL `href` 并使用服务 URL 在 `hx-get`。初始内容加载器为一发;空加载器 URL为惰性。 在主内容 401 上, shell 拥有登录导航, 并将页眉刷新到 5 秒; 延迟刷新不能覆盖更新的导航 .

普通内部 `<a href="/route">` 使用本地GET或POST的链接和表格会自动升级到HTMX,并通过自有服务进行路由. 默认 `#bp-main` 导航, 配置的 app UI 路由是权威的 `href` 和历史;运行时间从不推动未配置的服务路径. 一个赤裸的 `<form>` 设置到当前服务视图。 使用 `bp-no-override` (或 `data-bp-no-override`在元素或祖先上保持本地浏览器的行为; `data-bp-no-route` 用于壳体所属部件的剩余支持.

运行时管理的 HTMX 请求自动声明 `Accept: text/html; mode=page|fragment`; SSE 连接总是被标记 `HX-Request-Type: partial`,保留 SSE 介质类型,并获得与其他自助请求相同的范围 BP 认证/文本头. 明确非HTML `Accept` 头被保留了 .

也写着: `<meta name="betterportal:session-id" content="<uuidv7>">` 添加 `bp.session_id` 在每一次运行时间管理的请求中,到 W3C 行李。 一个文档负载的ID会持续, 以 `document.documentElement.dataset.bpSessionId`,并且只是相关性。 shells 应使框架提供的请求会话生效; 当元标记缺失时, 运行时间会产生倒数 .

对于初始外壳渲染, 展开 `betterPortalChromeAttributes(route.chrome)` 在标记的元素上 `data-bp-shell-root`。在路由响应后,运行时间将显示 `bp-chrome-*` 内容类型参数,更新相应的参数 `data-bp-chrome-*` 属性,删除 stale 属性,并调用可选键 `applyChrome(chrome, previousChrome, root)` 适生钩. 主题通常应对照数据属性和保留使用 CSS `applyChrome` 用于无法在CSS中表达的演示文稿。 主题不得注册重复的HTMX铬收听器,也不得从铬值推断出认证状态.

外壳适配器仅用于演示. 它们可实施加载/误入UI、组件初始化和处置、覆盖清理、滚动和可选的铬演示。 一个 shell 包不添加 `htmx.org`这个运行时间拥有并捆绑它。 此运行时间也导入 `jsx-htmx`,但外壳导入 `jsx-htmx` 对TSX来说,必须直接宣布它为自己的依赖。 不要捆绑库存预装扩展: BetterPortal 预装执行是其中的一部分 `bp-shell` 因此它可以附加范围化的BP头并再用前置反应. 固定的 HTMX 扩展允许列表是 `bp-shell, sse`。 。 。 .

运行时间测试包括无头铬预装还原. 从工作空间根运行 `npx playwright install chromium` 曾经 `npm test` (Linux CI 语法 `--with-deps`) (中文(简体) ).

Plain service sockets只有在完整启用的页面挂起解析后才能升级为主板HTMX. 单是预装标记并不能表示路由成功. 在 UI 挂载中声明时,会识别来自更古老 shell 元数据的编码服务模板占位符 。 自定义主题必须重建/重新配置其捆绑的共享运行时间以接收修正;见 [11.0.0 路线说明](https://github.com/BetterCorp/BetterPortal/blob/master/docs/releases/11.0.0.md)。 。 。 .

普通服务目的地在任何UI化名之前就解决自有服务问题。 属于另一服务的同名UI 挂载无法接管链接 。 壳牌自有导航明确标识. 配置的 UI 路径只有在没有自有服务目的地匹配时才是一个相容倒置.

## 常见问题

### @betterportal/theme-runtime 是什么？

主题包的后端组装更好的门户网站浏览器运行时间

### 如何安装 @betterportal/theme-runtime？

在项目目录运行 npm install @betterportal/theme-runtime，或使用 pnpm add / yarn add / bun add。

### @betterportal/theme-runtime 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @betterportal/theme-runtime 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @betterportal/theme-runtime 可以商用吗？

@betterportal/theme-runtime 使用 \(AGPL-3\.0-only OR Commercial\) 许可。可在 AGPL-3\.0、Commercial 中任选其一遵守。以上为概括，不构成法律意见，请以许可原文为准。

### @betterportal/theme-runtime 的下载量有多少？

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

### @betterportal/theme-runtime 还在维护吗？

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