# @chainrender/client 中文文档
规范地址：https://npmcn.com/package/%40chainrender/client/
版本：0\.17\.0
npm 元数据更新时间：2026-10-31T17:54:49.978Z
中文译文更新时间：2026-10-31T18:40:49.794Z
软件包许可：MIT
本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40chainrender/client
原文对照：https://npmcn.com/package/%40chainrender/client/?lang=original
项目主页：https://chainrender.org/
源码仓库：https://github.com/rfikki/chainrender
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：979 kB，193 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：viem ^2\.56\.3
- 首次发布：2026-09-08T13:58:57.261Z
- 最新版本发布：2026-10-31T17:54:49.857Z
- 已发布版本数：16（近 12 个月 16 个）
## 中文简介
ChainRender客户端SDK -无头，AST-first核心：编译，分级，构建，描述，验证和机器可读词汇表。可视化构建器、MCP服务器和人工智能助手的基础。
## 安装
```sh
npm install @chainrender/client
```
也可以使用：`pnpm add @chainrender/client`、`yarn add @chainrender/client`、`bun add @chainrender/client`
## README
# @chainrender /客户端
ChainRender的off-chain钩子层。它做两件事：
1. **渲染** 一个链上组件通过free `eth_call` （没有钱包，没有汽油）。
2. **绑定** 组件的数据绑定 _槽_ 实时值(余额、ENS名称、网络、 tx状况)。
它的核心是框架无关和无依赖的（它直接使用JSON-RPC） 手工完成所需的少量ABI编码/解码)。一个React适配器作为 单独的入口点。这反映了Scaffold-ETH是如何将wagmi -薄的、输入的帮助程序包裹在 下面的东西-除了“下面的东西”是ChainRender的链上解释器。
## 快速入门
安装:
```bash
npm install @chainrender/client viem
```
在10行左右的时间内将链上组件渲染为HTML -没有钱包，没有gas，只是一个免费的 `eth_call`：
```ts
import { renderComponent, bindSlots, staticResolvers, makeProviderResolvers } from "@chainrender/client";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
const deployment = {
rpc: "https://ethereum-sepolia-rpc.publicnode.com",
router: "0x0322b911900cb42694899eb06469c786f52e064c", // RenderRouter
registry: "0x36a443515b96b992ee397dfd9a533de72b70c3c9", // ComponentRegistry
};
// 1. render the component (by its content hash) to an escaped HTML string
const html = await renderComponent(deployment, "0x…componentHash");
// 2. mount it in an isolated shadow root
const shadow = document.getElementById("app").attachShadow({ mode: "open" });
shadow.innerHTML = html;
// 3. fill any live data-binding slots (balances, ENS, tx status)
const publicClient = createPublicClient({ chain: sepolia, transport: http(deployment.rpc) });
await bindSlots(shadow, { ...staticResolvers, ...makeProviderResolvers(publicClient) });
```
这就是整个循环： **链上渲染→挂载→绑定实时数据。** `viem` 是一个对等依赖（任何兼容的提供商都可以工作）；React和Farcaster迷你应用适配器是可选的入口点（见下文）。要发现组件散列，请对注册表的散列建立索引 `ComponentRegistered` 事件，或使用 `enumerate(deployment)` 获取一个快速的概念验证列表。
## 为什么槽
ChainRender组件是不可变的，内容寻址的，并且存储在链上，所以是实时数据 （每个区块都会改变的余额，通过CCIP-Read解析的ENS名称）无法被纳入 他们。相反，链上解释器发出 **槽** -一个转义的占位符，如：
```html
—
```
占位符呈现其回退，直到此库填充它为止。ENS和balance绑定 本质上是客户端，因为合约不能执行CCIP-Read HTTP 需求;这就是链下层与链上解析器钩子一起存在的全部原因。
## 核心用法（任何框架）
```ts
import { renderComponent, bindSlots, staticResolvers, makeProviderResolvers } from "@chainrender/client";
const deployment = { rpc: "https://…", router: "0x…", registry: "0x…" };
// 1. render on-chain -> escaped HTML string
const html = await renderComponent(deployment, componentHash);
// 2. mount into an isolated container (shadow root recommended)
const host = document.createElement("div");
const shadow = host.attachShadow({ mode: "open" });
shadow.innerHTML = html;
// 3. fill the slots with live data (pass a viem PublicClient, or any compatible provider)
await bindSlots(shadow, { ...staticResolvers, ...makeProviderResolvers(publicClient) });
```
`enumerate(deployment)` 列出已注册的组件(链上的概念验证枚举 生产应用程序应该索引注册表 `ComponentRegistered` 事件相反)。
## 反应的使用
```tsx
import { ChainRenderView, useChainRenderComponent } from "@chainrender/client/react";
import { staticResolvers, makeProviderResolvers } from "@chainrender/client/resolvers";
const resolvers = { ...staticResolvers, ...makeProviderResolvers(publicClient) };
```
`styleSheet` 接受从ChainRender Explorer导出的off-chain主题样式表，因此 该组件选择你的颜色和字体比例。 `react` 是一个可选的对等依赖；这个 核心入口没有框架依赖。
## 内置槽位绑定
`staticResolvers` 覆盖不需要链访问的绑定(`address`， `networkName`， `avatar` 占位符, `txStatus` 回退)。 `makeProviderResolvers(provider)` 添加活的 （`balance`， `ensName`， `ensNameOrAddress`， `avatar`， `networkName`)，使用兼容的浏览器 提供者。通过扩展解析器映射来添加您自己的映射-键是插槽的 `data-cr-bind` 种类。
## 第一方链上解析器类型
与上面的客户端运行时解析器（填充浏览器中的槽）不同，有些槽 绑定到 **链上** 解析器 _种类_． ChainRender提供了一个大型的第一方集合- DeFi， oracle， 凭据、ENS、认证、RWA、声誉、CCIP、消息传递、结算、跨链证明等等 中列出的 `RESOLVER_KINDS` 和 `vocabulary().resolverKinds` （类型、参数、数据边缘、能力、注释）和暴露 每个家庭 `kinds`，用他们的 `KIND_*` 常量和参数编码器，例如：
- `kinds.oracle` - oracle feeds (`KIND_FEED`， `encodeFeedArgs`）。
- `kinds.credential` / `kinds.credentialBound` -选择性披露和绑定一次性凭证。
- `kinds.ens` - - - - - - `encodeAddrArgs(node)`， `encodeTextArgs(node, key)`， `encodeNameArgs(address)`， `encodeV2Args(resolver, inner, isText)` 与 `v2AddrCall` / `v2TextCall`.
对插槽进行编码 `arg` 正如它的描述所言： `abi.encode` 时的原始字节 描述符有 `argsEncoding: "packed"` （`ensName` 正好占用20个地址字节)。完整的名单在 [https://chainrender.org/docs/reference/resolver-kinds.html](https://chainrender.org/docs/reference/resolver-kinds.html)． 解析器类型有 **第一方但可扩展** -你可以部署你的 自己的解析器服务于一种新的类型；这是一组ChainRender船只，而不是一个封闭的词汇表。
## 在编译树之前检查它
`compile()` 静默地丢弃它不读取的任何东西——未知字段、不在字典中的枚举值 （`role: "note"`)，图像上的所有字段； `args` 在批处理成员上。 `checkNode(tree)` 报告每个路径 并强制节点/深度/大小限制； `nodeJsonSchema()` 与AI工具的严格JSON模式规则相同。
```ts
import { checkNode, nodeJsonSchema } from "@chainrender/client";
const r = checkNode(tree); // { ok, issues: [{ path, code, message }], nodeCount, depth }
```
## 安全
`bindSlots` 集合 `textContent`，因此解析后的值将作为文本插入，而不会被解析为 超文本标记语言。解释器的输出已经被转义了。渲染成一个阴影根或沙盒 框架下严格的内容安全策略，而不是天真的 `innerHTML` 有特权的人 页面。
## 安装和网络
```
npm install @chainrender/client viem
```
`viem` 是一个对等依赖。包裹是 **chain-agnostic** -它没有地址，没有 `chainId`，没有RPC。从部署中注入客户机/RPC和契约地址，因此 同样的包可以在Sepolia， mainnet或任何L2上工作：
```ts
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
const client = createPublicClient({ chain: sepolia, transport: http(RPC_URL) });
// point renders/binds at the addresses from your deployment's addresses.json
```
Sepolia注释（数据，而不是代码）：使用Sepolia部署的地址；如果组件绑定了Chainlink feed，使用Sepolia feed地址（或部署的模拟）——一个主网feed地址在Sepolia上返回；和 ENS可以机械地进行解析，但塞波利亚的注册名称要少得多。
## 构建
```
npm run build # tsc -p tsconfig.build.json → self-contained dist/
```
构建过程将客户端与控件一起编译 `chainc/` 镜像分为 `dist/`，所以出版了 包中没有可以转义它的导入。 `prepublishOnly` 在之前自动运行 `npm publish`.
## 发行方式：Farcaster迷你应用/标准网页应用
`@chainrender/client/miniapp` 是一个薄的，失败封闭的包装，呈现一个ChainRender应用程序作为一个 Farcaster迷你应用程序 **和** 一个普通的标准web应用程序。链上渲染是底层的工作 独立的;迷你应用层（嵌入标签，FID / Sign In With Farcaster，通知，钱包）是 渐进式增强，在Farcaster主机外无操作。
```ts
import { buildManifest, buildEmbedMetaTags, capabilitiesForEnvelope } from "@chainrender/client/miniapp";
import { mountChainRenderApp, signInWithFarcaster } from "@chainrender/client/miniapp";
// build /.well-known/farcaster.json (add the account association from the Farcaster dev tools)
const manifest = buildManifest({
name: "My Component", homeUrl: "https://my.app", iconUrl: "https://my.app/icon.png",
requiredChains: ["eip155:11155111"], // Sepolia
requiredCapabilities: capabilitiesForEnvelope(envelope), // carries the ChainRender capability honesty
});
// in the page: render the on-chain floor, then signal the host
await mountChainRenderApp(async () => { /* inject the eth_call HTML into the DOM */ });
```
`@farcaster/miniapp-sdk` 是一个 **可选** 对等依赖，惰性加载-适配器构建和 运行没有它（标准的web应用程序模式）。看到 `examples/miniapp-wrapper.html` 对于一个完整的页面 是一款网页应用，也是一款迷你应用。
## 常见问题
### @chainrender/client 是什么？
ChainRender客户端SDK -无头，AST-first核心：编译，分级，构建，描述，验证和机器可读词汇表。可视化构建器、MCP服务器和人工智能助手的基础。
### 如何安装 @chainrender/client？
在项目目录运行 npm install @chainrender/client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（^2\.56\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @chainrender/client 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @chainrender/client 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @chainrender/client 可以商用吗？
@chainrender/client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @chainrender/client 还在维护吗？
最新版本 0\.17\.0 发布于 2026/11/01（2 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/09/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。