@ptengine/ui-react

@ptengine/ui 的 React 包装层。主体由构建自动生成 —— src/components/ 下的文件是 Stencil 的 React output target 在 pnpm build 时产出的，不要手改。 另有几份手写补丁替换了个别生成的导出：hydration-hold.ts / hydration-hold.server.ts （PtCollapsible、PtMenu、PtPopover、PtTooltip，推迟到水合之后再给触发元素写 ARIA）与 opaque-light-dom.ts（PtPaginationItem，让 React 不比对它的子节点）。

安装

npm i @ptengine/ui-react

样式表

不用手动引：第一个组件连上页面时，会把设计变量（ptengine-ui.css 的内容）自动挂到 document 上。

服务端渲染的项目建议手动引一次，否则 JS 到达之前首屏没有样式、会闪一下。引了的话自动注入会跳过。 放在根组件里（Next.js 是 app/layout.tsx，React Router 是 app/root.tsx），并把 @ptengine/ui 装成直接依赖（npm i @ptengine/ui，pnpm 下间接依赖找不到）：

import '@ptengine/ui/dist/ptengine-ui/ptengine-ui.css';

用法

import { PtButton, PtInput } from '@ptengine/ui-react';

export function Form() {
  const [value, setValue] = useState('');

  return (
    <>
      <PtInput value={value} onPtChange={event => setValue(event.detail)} />
      <PtButton variant="brand">提交</PtButton>
    </>
  );
}

内核里的事件是 ptChange，React 侧生成 onPtChange，event.detail 带类型。

服务端渲染

// Server Component
import { PtBadge } from '@ptengine/ui-react/ssr';

从 /ssr 导入的组件在服务端渲染成 Declarative Shadow DOM，首屏不闪烁。 需要交互的部分仍从 @ptengine/ui-react 导入，放在 'use client' 组件里。

例外：pt-kbd、pt-kbd-group、pt-breadcrumb-item、pt-pagination、pt-pagination-item 不参与服务端渲染 （/ssr 导出的是客户端版本）。前三个的文字或链接由使用方写在标签里，首屏照常可见；分页项的链接由组件按属性渲染， 首屏只有空标签，升级后才出现。详见文档站的「服务端渲染」一页。

next.config.mjs 里要声明 transpile（这几个包发的是未编译的 ESM）：

export default {
  transpilePackages: ['@ptengine/ui', '@ptengine/ui-react']
};

轻提示（toast）

命令式的 toast() 从 @ptengine/ui/toast 导入。 <PtToaster /> 挂在根组件末尾一次即可；不挂也能用， toast() 会在 <body> 末尾建一个：

import { PtToaster } from '@ptengine/ui-react';
import { toast } from '@ptengine/ui/toast';

// 根组件里：<PtToaster position="top-center" richColors />
toast.success('已保存');

版本

与 @ptengine/ui 锁步发版、共用一个版本号。React 18 与 19 都支持。