# @evelan/jexity-widget 中文文档

规范地址：https://npmcn.com/package/%40evelan/jexity-widget/

版本：0\.35\.0
npm 元数据更新时间：2026-11-13T03:04:14.803Z
中文译文更新时间：2026-11-14T07:13:53.003Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40evelan/jexity-widget
原文对照：https://npmcn.com/package/%40evelan/jexity-widget/?lang=original
项目主页：https://github.com/evelan-de/jexity-chatbot/tree/main/apps/widget#readme
源码仓库：https://github.com/evelan-de/jexity-chatbot

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

- 包体积（解压后）：6.1 MB，276 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：react \>=18
- 首次发布：2026-03-04T00:49:05.739Z
- 最新版本发布：2026-11-13T03:04:14.407Z
- 近 30 天下载量：2154（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：85（近 12 个月 85 个）

## 中文简介

Evelan 的可嵌入的 AI 聊天部件 — 在任何网站添加客户支持聊天, 并安装一个脚本标签或 npm

## 安装

```sh
npm install @evelan/jexity-widget
```

也可以使用：`pnpm add @evelan/jexity-widget`、`yarn add @evelan/jexity-widget`、`bun add @evelan/jexity-widget`

## README

# @evelan/ jexity- widget (英语)

任何网站的可嵌入的 AI 聊天部件 。 以单个方式添加客户支持聊天 `<script>` 标记或通过 npm.

## 快速启动

### 脚本标记( 不需要构建工具)

```html
<script
  src="https://cdn.jexitychat.de/widget/latest/widget.js"
  data-org-slug="YOUR_ORG_SLUG"
  async
></script>
```

### 国家预防机制

```bash
npm install @evelan/jexity-widget
```

```ts
import { JexityChat } from '@evelan/jexity-widget'

const chat = JexityChat({
  orgSlug: 'YOUR_ORG_SLUG',
})

// Later:
chat.shutdown()
```

### 反应提供者

```tsx
import { JexityChatProvider, useJexityChat } from '@evelan/jexity-widget/react'

function App() {
  return (
    <JexityChatProvider orgSlug="YOUR_ORG_SLUG">
      <HomePage />
    </JexityChatProvider>
  )
}

function HomePage() {
  const { open, close, toggle, isOpen } = useJexityChat()
  return <button onClick={open}>Chat with us</button>
}
```

### 已签名的用户: 在您的服务器上签名

`@evelan/jexity-widget/server` 为在服务器上签名的用户(Node 20+、Next.js 路由处理器、边缘运行时间、Convex、Deno、Bun)签名。 无依取相. 密钥决定了算法:来自Sign-in窗口的签入密钥会标出HS256,一个P-256的私人密钥(JWK),其公用半是已注册的口号ES256.

```ts
// app/api/jexity-pass/route.ts (Next.js)
import { createJexityPass } from '@evelan/jexity-widget/server'

export async function GET() {
  const user = await getSignedInUser() // your app's own login, checked on the server
  if (!user) return new Response('', { status: 401 })
  const pass = await createJexityPass(
    { userId: user.id, name: user.name, email: user.emailVerified ? user.email : null, accountId: user.companyId },
    process.env.JEXITY_SIGN_IN_KEY,
  )
  return new Response(pass)
}
```

它把通行证保存在Jexity接受的:一个长名被剪去,一个无效的电子邮件被漏掉, `iat`编号 :`exp` 秒,默认1小时(`{ lifetimeSeconds }` 最多24小时的通行证)。 一个用户代号超过128个字符投出而不是被剪取,因此两个用户从不共享聊天. 断开的密钥会丢出一个永远不重复的固定消息.

* * *

## 配置

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `orgSlug` | `string` | **所需经费** | 您的组织 slock( 例如). `acme-corp`(中文(简体) ) |
| `container` | `string | HTMLElement` | 自动创建 `div` | CSS 选择器或要上载的元素 |
| `position` | `'bottom-right' | 'bottom-left'` | `'bottom-right'` | 屏幕上的部件位置 |
| `colorScheme` | `'light' | 'dark' | 'auto'` | `'auto'` | 强制颜色方案; `'auto'` 遵循系统偏好 |
| `title` | `string` | `'Jexity Assistant'` | 聊天窗口标题 |
| `greeting` | `string` | `'Hi! How can I help?'` | 打开时显示的初始机器人消息 |
| `primaryColor` | `string` | `'#0070f3'` | 短手品牌颜色 — 线条 FAB, 标题, 用户泡泡, 发送按钮 |
| `accentColor` | `string` | —— 说 | 次要口音颜色 |
| `fontFamily` | `string` | —— 说 | 覆盖部件字体家族 |
| `fontSize` | `number` | —— 说 | Px 中的基础字体大小 |
| `borderRadius` | `string` | —— 说 | 覆盖部件角半径( 如 . `'8px'`(中文(简体) ) |
| `windowWidth` | `number` | —— 说 | 聊天窗口宽度以 px 为单位 |
| `windowHeight` | `number` | —— 说 | 在 px 中聊天窗口高度 |
| `triggerIcon` | `'chat' | 'bot' | 'sparkles'` | `'chat'` | 浮动动作按钮图标 |
| `triggerRadius` | `'none' | 'sm' | 'md' | 'lg' | 'full'` | `'full'` | FAB 边界半径形状 |
| `triggerLabel` | `string` | —— 说 | FAB 旁边显示的文本标签 |
| `hideBranding` | `boolean` | `false` | 隐藏“ 由 Jexity 授权” 页脚 |
| `locale` | `string` | 浏览器 / `'de'` | 强制地点( E)`'de'` | `'en'`) (中文(简体) ). 覆盖浏览器检测 |
| `parentOrigin` | `string` | `window.location.origin` | 后Message 仪表板预览更新的可信来源 |
| `theme` | `JexityTheme` | —— 说 | 颗粒每个元素的颜色覆盖(见下文) |
| `userToken` | `string | () => string | Promise<string>` | —— 说 | 签名用户通行证:JWT您的 **服务器** 带有项目登录密钥的标志,最好 `createJexityPass` 从 `@evelan/jexity-widget/server` (HS256带密钥,ES256带注册公用钥匙的私用钥匙的一半) (`sub`选项 `name`, (中文(简体) ), `email`, (中文(简体) ), `account_id`, (中文(简体) ), `iat`, (中文(简体) ), `exp` 24小时). 每个靴子上都有一个功能,包括小时刷新. 被拒绝的通行证会停止部件; 它永远不会回到匿名状态 。 脚本标签 : `data-user-token`。另一个用户(更改属性或字符串道具)的通行证从头开始;带有函数,调用 `logout()` 在注册。 参见帮助中心: _识别登录用户_。 。 。 . |

### 外观主题覆盖

`theme` 让您覆盖单个元素颜色。 未设置的密钥返回到 `primaryColor` 或品牌默认.

```ts
JexityChat({
  orgSlug: 'acme',
  theme: {
    bg: {
      trigger: '#1a1a2e',    // FAB background
      header: '#16213e',     // Chat header
      msgUser: '#0f3460',    // User bubble background
      msgBot: '#f5f5f5',     // Bot bubble background
      window: '#ffffff',     // Chat window background
      sendBtn: '#e94560',    // Send button background
    },
    text: {
      header: '#ffffff',     // Header text/icon color
      msgUser: '#ffffff',    // User bubble text
      msgBot: '#333333',     // Bot bubble text
      main: '#212121',       // Primary body text
      muted: '#888888',      // Secondary/muted text
    },
    border: {
      window: '#e0e0e0',     // Window border
      input: '#cccccc',      // Input field border
    },
  },
})
```

* * *

## 程序化 API

```ts
const chat = JexityChat(options)

chat.open()                    // Open the chat window
chat.close()                   // Close the chat window
chat.toggle()                  // Toggle open/closed
chat.ask("How do I crawl?")    // Open the chat and send this question
chat.shutdown()                // Remove widget from DOM
chat.logout()                  // Signed-in user signed out: forget this tab's chats, start over with the current pass
chat.isOpen                    // readonly boolean — current open state
chat.subscribe(cb)             // Subscribe to open/close changes
                               // Returns unsubscribe function

// Your user signed out, also before the chat has loaded on this page:
import { logout } from "@evelan/jexity-widget" // or "@evelan/jexity-widget/react"
logout()                       // Forget this tab's chats

// IIFE global (script tag):
window.JexityChat.open()
window.JexityChat.close()
window.JexityChat.toggle()
window.JexityChat.shutdown()
```

* * *

## IIFE (脚本标记) 属性

所有选项都可设置为 `data-*` 属性 `<script>` 标签 :

```html
<script
  src="https://cdn.jexitychat.de/widget/latest/widget.js"
  data-org-slug="acme-corp"
  data-locale="de"
  data-primary-color="#ff6600"
  data-trigger-icon="sparkles"
  data-trigger-radius="lg"
  data-trigger-label="Chat with us"
  data-hide-branding="true"
  data-convex-url="https://your-deployment.convex.cloud"
  async
></script>
```

然后在装入后进行程序控制 :

```html
<script>
  window.JexityChat.open()
  window.JexityChat.shutdown()
</script>
```

* * *

## 构建产出

```
dist/
  widget.js          ← IIFE for <script> embed (CDN)
  index.mjs          ← ESM for bundlers (npm)
  react.mjs          ← React bindings (externalizes react + core)
  server.mjs/.cjs    ← createJexityPass for your server (no Preact, React or Convex)
  types/index.d.ts   ← TypeScript declarations (core)
  types/react.d.ts   ← TypeScript declarations (React)
```

目标规模: IIFE → 32 KB → 无害环境管理 → 42 KB(宽度)

* * *

## 发展

```bash
# From repo root:
pnpm dev --filter @evelan/jexity-widget

# Or directly:
cd apps/widget
pnpm dev
```

打开 **`http://localhost:3002`** ——dev游乐场设有活化配置控制.

### 环境变量

创建 `apps/widget/.env.local`数字 :

```bash
# Convex deployment URL — used for both WebSocket (real-time) and HTTP actions (config fetch).
# The widget auto-derives .convex.site from .convex.cloud via convex-url.ts.
# Copy from packages/backend/.env.local (CONVEX_URL).
VITE_CONVEX_URL=https://<your-dev-deployment>.convex.cloud

# Reserved — not consumed yet. Future escape hatch if we ever swap Convex for
# a traditional REST backend (Express, Fastify, etc.). Once wired, widget code
# will read this instead of VITE_CONVEX_URL so the backend is hot-swappable
# via env alone.
# VITE_API_BASE_URL=https://api.example.com
```

### URL 参数

| 参数 | 示例 | 目的 |
| --- | --- | --- |
| `?orgSlug=` | `?orgSlug=demo` | 设置 Org sattle( 默认 ): `dev_local`(中文(简体) ) |
| `?primaryColor=` | `?primaryColor=%230070f3` | 设置主颜色 |
| `?locale=` | `?locale=en` | 锁定地盘 |
| `?position=` | `?position=bottom-left` | 部件位置 |
| `?title=` | `?title=My+Assistant` | 部件标题 |
| `?hideBranding=true` | —— 说 | 隐藏页脚品牌 |
| `?skipHomeScreen=true` | —— 说 | 直接打开聊天( skip 登陆) |

### 构建

```bash
pnpm build          # Full build (all 5 outputs)
pnpm check-types    # Type-check only (fast)
```

* * *

## 许可证

麻省理工学院

## 常见问题

### @evelan/jexity-widget 是什么？

Evelan 的可嵌入的 AI 聊天部件 — 在任何网站添加客户支持聊天, 并安装一个脚本标签或 npm

### 如何安装 @evelan/jexity-widget？

在项目目录运行 npm install @evelan/jexity-widget，或使用 pnpm add / yarn add / bun add。

### @evelan/jexity-widget 支持 TypeScript 吗？

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

### @evelan/jexity-widget 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @evelan/jexity-widget 可以商用吗？

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

### @evelan/jexity-widget 的下载量有多少？

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

### @evelan/jexity-widget 还在维护吗？

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