# @descope/web-component 中文文档

规范地址：https://npmcn.com/package/%40descope/web-component/

版本：4\.7\.0
npm 元数据更新时间：2026-11-08T15:37:00.930Z
中文译文更新时间：2026-11-12T00:51:01.459Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40descope/web-component
原文对照：https://npmcn.com/package/%40descope/web-component/?lang=original
项目主页：https://github.com/descope/descope-js
源码仓库：https://github.com/descope/descope-js

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

- 包体积（解压后）：1.6 MB，125 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2022-09-05T11:54:25.899Z
- 最新版本发布：2026-11-08T15:37:00.754Z
- 近 30 天下载量：1539045（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：658（近 12 个月 165 个）

## 中文简介

望远镜WC

## 安装

```sh
npm install @descope/web-component
```

也可以使用：`pnpm add @descope/web-component`、`yarn add @descope/web-component`、`bun add @descope/web-component`

## README

# @ descope/ web- 组件

在控制台应用程序上创建您的登录页面, 完成后, 您可以使用此库向您的应用程序注入这些页面  
它记录着.. [网络组件](https://developer.mozilla.org/en-US/docs/Web/Web_Components) 并根据相关网页更新网页内容, 见下文使用实例

## 使用量

### 安装软件包

```bash
npm install @descope/web-component
```

### 作为图书馆

```js
import '@descope/web-component' // This import will define `descope-wc` custom element
import { DescopeWc } // In case you need types definition or you want to use the class directly

// Render Descope Web Component, for example:
render(){
  return (
    <descope-wc project-id="myProjectId"/>
  )
}
```

### 在 HTML 文件内

-   复制文件 `@descope/web-component/dist/index.js` 重命名为 `descope-wc.js` 并将其放置在您的 HTML 文件所在位置
    
-   将以下脚本标签添加到您的 HTML 文件
    

```html
<head>
  <script src="./descope-wc.js"></script>
</head>
```

-   现在可以将自定义元素添加到您的 HTML

```html
<descope-wc project-id="<project-id>" flow-id="<flow-id>" form='{ "email": "predefinedname@domain.com", "myCustomInput": "12" }' client='{ "browserVersion": window.navigator.appVersion }'></descope-wc>
```

-   说明: `form` 财务报告和审定财务报表 `client` 是可选参数,用于添加可在流量中使用的额外信息。 详情 [点击这里](https://docs.descope.com/knowledgebase/descopeflows/flowinputs/#HTML)。 。 。 .

### 运行示例

举例来说:

1.  安装依赖关系 `pnpm i`
2.  创建一个 `.env` 文件与以下变量:

```env
// .env
# Descope Project ID
DESCOPE_PROJECT_ID=<project-id>
# Flow ID to run, e.g. sign-up-or-in
DESCOPE_FLOW_ID=<flow-id>
# Optional - Descope base URL
DESCOPE_BASE_URL
# Optional - Descope locale (according to the target locales configured in the flow)
DESCOPE_LOCALE=<locale>

# Telemetry fallback config (AWS CloudWatch RUM).
# Optional — used by the SDK only when the backend's config.json doesn't
# ship a `telemetry` block. Once it does, these are ignored.
# Leave DESCOPE_TELEMETRY_ENABLED unset or set to anything other than
# "true" to keep the fallback off.
DESCOPE_TELEMETRY_ENABLED=<true|false>
DESCOPE_TELEMETRY_APPLICATION_ID=<cloudwatch-rum-app-monitor-id>
DESCOPE_TELEMETRY_IDENTITY_POOL_ID=<aws-cognito-identity-pool-id>
DESCOPE_TELEMETRY_REGION=<aws-region>
# Optional — only required for the classic Cognito flow.
DESCOPE_TELEMETRY_GUEST_ROLE_ARN=<iam-guest-role-arn>
# Optional — 0..1, defaults to 1 (capture every session).
DESCOPE_TELEMETRY_SESSION_SAMPLE_RATE=1
```

1.  运行样本 `pnpm run start` 编号 : `pnpm run start-web-sample`

注: 这个包是单列波的一部分. 所以,如果您在依赖关系上有所改变,您必须重新运行 `npm run start` 编号 : `pnpm run start-web-sample` (这是暂时的解决方案,直到我们改进过程以适应单重).

## 安全特性

### 分资源廉正

网页组件自动应用 [分资源廉正](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) 当项目配置中存在SRI散列时, 请检查网络组件- ui 加载器 。 这提供了加密验证,说明所装入的脚本没有被篡改.

**如何运作:**

1.  Descope 管弦乐服务为每个版本的网络组件- ui 库生成 SRI 散列
2.  散列包含在 `config.json` 作为 `componentsVersionSri`
3.  网络组件自动添加 `integrity` 财务报告和审定财务报表 `crossorigin` 脚本标签属性
4.  浏览器在执行前验证脚本完整性

**生成脚本标签示例 :**

```html
<script src="https://descopecdn.com/npm/@descope/web-components-ui@1.0.0/dist/umd/index.js" integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K..." crossorigin="anonymous"></script>
```

**内容安全政策相容性 :**

SRI与CSP合作无缝. 对于严格的CSP配置,将SRI与 `nonce` 属性 :

```html
<descope-wc project-id="myProjectId" flow-id="sign-up-or-in" nonce="random-nonce-value"></descope-wc>
```

**CSP 标题示例 :**

```
Content-Security-Policy:
  script-src 'self'
    https://descopecdn.com
    https://static.descope.com
    https://cdn.jsdelivr.net
    'nonce-random-nonce-value';
```

**后向兼容性 :**

如果配置(更老的项目)中没有SRI散列,组件通常会不进行完整性检查而加载. 不需要中断更改 .

### 跨源 OAuth 弹出

当 OAuth 弹出重定向页面的出处不同于打开它的页面时(参见 `popup-origin`),弹出会只将OAuth结果寄给开源Descope证明弹出. Descope证明,当弹出是项目核准的域之一时,或者当项目没有核准的域时,打开弹出页的出处. 否则,弹出只回答同一个来源 `BroadcastChannel`,因此列出项目核准域中的主要应用程序域.

## 可选属性

| 属性 | 可用选项 | 默认值 |
| --- | --- | --- |
| 基准url | 自定义查看镜基址 | **"" "" (英语)** |
| 主题 | **"轻"** - 轻主题  
**"黑暗"(暗语)** - 黑暗主题  
**"欧"** - 根据OS主题设置自动选择主题 | **"轻"** |
| 调试 | **"对"** - 启用调试器  
**假话** - 禁用调试器 | **假话** |
| 预览 | **"对"** - 在预览模式下运行流量  
**假话** - 在预览模式下运行流量 | **假话** |
| 自动焦点 | **"对"** - 自动注重每个屏幕的第一个输入  
**假话** - 不要自动关注屏幕输入  
**"史克威尔"** - 自动关注每个屏幕的第一个输入,但第一个屏幕除外 | **"对"** |
| 自动验证 | **"对"** - 除提交时的验证外,在模糊时触发输入验证  
**假话** - 模糊时不要触发验证  
 | **假话** |
| 重新启动错误 | **"对"** - 如果流量版本不匹配,如果组件版本没有更改,则会重新启动流量  
**假话** - 不要自动重新启动流量  
 | **假话** |
| 发送会话 | **"对"** - 在流程启动/下期请求中发送当前会议JWT,使其经证实的债权通过流程 `sessionJwtClaims` 上下文键  
**假话** - 不发送会话 JWT  
 | **假话** |
| 存储前缀 | **字符串** - 当持续符号时添加本地存储键的前缀 | **"" "" (英语)** |
| 存储最后认证的用户 | **"对"** - 完成流动后,将最后核证的用户细节存储在本地存储中  
**假话** - 不要存储最后的用户细节 。 禁用此旗帜可能导致上次认证的用户特性无法正常运行 | **"对"** |
| 保留最后认证的用户后日志 | **"对"** - 登录后不要从浏览器存储中清除最后经过认证的用户细节  
**假话** - 登录后从浏览器存储中清除最后认证的用户细节 | **假话** |
| 样式编号 | **"竖起"** - 设置一个特定的样式来装入默认样式 | **"" "" (英语)** |
| 无 | **"竖起"** - 设置用于样式和脚本标记的 CSP 非ce 。 与SRI合作加强安全 | **"" "" (英语)** |
| 弹出源 | **"竖起"** - 设定 OAuth 弹出通信的预期来源, 当重定向 URL 与主应用程序不同时。 跨源 OAuth 弹出流量需要 | **"" "" (英语)** |
| 取消屏幕输入 | **"对"** - 清除用户输入的屏幕错误信息  
**假话** - 在用户输入时不清除屏幕错误消息 | **假话** |
| 境外申请编号 | **"竖起"** - 用于连接外部服务的外部应用程序ID | **"" "" (英语)** |
| 外出应用范围 | **"生平编"** - JSON 系列范围,用于请求出界应用程序(例如“\[“电子邮件”、“简介”\]) | **无效** |

## 可选属性

### `errorTransformer` - 接收出错对象并返回字符串的函数。 返回的字符串将显示给用户 .

该功能可用于将出错消息翻译为用户语言,或更改出错消息.

用法示例:

```javascript
function translateError(error) {
  const translationMap = {
    SAMLStartFailed: 'No es posible iniciar sesión en este momento, por favor intenta nuevamente más tarde',
  };
  return translationMap[error.type] || error.text;
}

const descopeWcEle = document.getElementsByTagName('descope-wc')[0];

descopeWcEle.errorTransformer = translateError;
```

### `logger` - 定义如何记录错误、警告和信息的对象。 分别默认控制台.error,控制台.warn和控制台.info

用法示例:

```javascript
const logger = {
  info: (message: string, description: string, state: any) => {
    console.log(message, description);
  },
  warn: (title: string, description: string) => {
    console.warn(`WARN: ${title}`, description);
  },
  error: (title: string, description: string) => {
    console.error(`ERROR: ${title}`, description);
  },
};

const descopeWcEle = document.getElementsByTagName('descope-wc')[0];

descopeWcEle.logger = logger;
```

### `onScreenUpdate`

当出现新屏幕状态时, 并在每次呼叫后, 都会调用此功能 。 它得到以下参数:

-   `screenName`: 即将渲染的屏幕名称
-   `context`: 包含即将到来的屏幕状态的对象
-   `next`: 当调用时继续流执行的函数
-   `ref`: 提及去镜-wc节点

该函数可以是同步或async,并且应当返回布尔表示是否应该渲染自定义屏幕:

-   `true`: 渲染自定义屏幕
-   `false`: 渲染默认流程屏幕

> **断裂变化( v4. 0.0) :** 服务器生成的用于直接显示的屏幕数据 `context` 现在生活在 **`context.data`** - 比如说. `context.totp` → `context.data.totp`, (中文(简体) ), `context.inboundAppApproveScopes` → `context.data.inboundAppApproveScopes`现状, `form`,和身份字段(`user` 编号 : `project` 编号 : `lastAuth`)住顶上. 见 [这个 `context` 对象](https://npmcn.com/package/%40descope/web-component/#readme-the-context-object) 完整清单 `context.data` 字段.

此功能允许渲染自定义屏幕而不是默认的流程屏幕. 对于高度定制化的 UI 或默认屏幕未覆盖的特定逻辑来说,它可能有用

为了制作自定义屏幕,其内容应作为儿童随附 `descope-wc` 组件

用法示例:

```javascript
function onScreenUpdate(screenName, context, next, ref) {
  if (screenName === 'My Custom Screen') {
    ref.innerHTML = `
          <form>
            <input type="text" name="email" placeholder="Email" />
            <button type="submit">Submit</button>
          </form>
        `;

    ref.closest('form').addEventListener('submit', (e) => {
      e.preventDefault();
      const formData = new FormData(e.target);
      const data = Object.fromEntries(formData.entries());

      // replace with the button interaction id
      next('interactionId', data);
    });

    return true;
  }

  return false;
}

const descopeWcEle = document.querySelector('descope-wc');

descopeWcEle.onScreenUpdate = onScreenUpdate;
```

#### 这个 `context` 对象

`context` 携带即将到来的屏幕状态 :

-   **顶级** —— 说 `error`, (中文(简体) ), `action`, (中文(简体) ), `form` (输入/输出渠道)和 用户上下文 : `user`, (中文(简体) ), `project`, (中文(简体) ), `lastAuth`。 。 。 .
-   **`context.data`** 所有服务器制作的屏幕数据 在一个干净稳定的地方,所以你 不需要阅读 内部,深沉的路径.

例如,一个生成 MFA 恢复代码的屏幕会将它们暴露为平面阵列:

```javascript
function onScreenUpdate(screenName, context, next, ref) {
  if (screenName === 'Display recovery codes') {
    const codes = context.data.recoveryCodes; // string[]
    // render the codes in your custom UI…
    return true;
  }
  return false;
}
```

`context.data` 可能包括(每个屏幕产生时才会显示):

-   `recoveryCodes` - 生成外交部的回收代码(`string[]`(中文(简体) )
-   `totp` 编号 : `notp` 外交部设置(图像、提供/直接URL)
-   `sentTo` - 传送检察官办公室/编码的地方(用口罩的电子邮件/电话)
-   `inboundAppApproveScopes` - 范围 入境应用程序要求用户批准
-   `passwordPolicy` - 显示/执行密码规则
-   `securityQuestionsSetup` 编号 : `securityQuestionsVerify` - 安全问题
-   `userTenants`, (中文(简体) ), `userRoles`, (中文(简体) ), `ssoApplications`, (中文(简体) ), `ssoConfigurations` - 选择选项
-   `samlAttributeMappings`, (中文(简体) ), `oidcAttributeMappings`, (中文(简体) ), `samlGroupMappings` ——SSO测绘
-   `sso` ——SSO服务提供者配置
-   `selfProvisionDomains` - 租户自给领域
-   `outboundApp` ——出局 OAuth 应用程序按钮信息

`context.data` 是一个由 SDK 拥有的支持,稳定的字段—— 与其读取,不如读取 原始屏幕状态内部。 它只暴露了上面有记录的字段;任何其他字段 内部屏幕状态数据被故意省略。 在 SDK 发布中添加了新字段.

每把钥匙 `context.data` 是一个SDK拥有,有文件记载的名称。 SDK从不说 任意、自定义键直接打开 `context.data`,所以总是添加新字段 没有打破已有的.

**尚未曝光 :** 动态选择选项( 其选项被计算出来的选定组件) 以流动盟誓, 它们的键是流本身的字段名,所以它们不符合固定形状 以上;暂时略去,保留给未来 `context.data.selects` 地图。 这个 以前没有自定义屏幕可用的数据,所以对现有代码没有任何修改.

> **断裂变化( v4. 0.0) :** 曾经直接显示的屏幕数据字段 `context` 现在住在下面 `context.data`。移动读取相应,例如. `context.inboundAppApproveScopes` → `context.data.inboundAppApproveScopes`, (中文(简体) ), `context.totp` → `context.data.totp`现状, `form`字段 (单位:千美元)`user`编号 :`project`编号 :`lastAuth`)住顶上.

## 活动

### `error` - 出错时开火 事件细节包含出错对象.

用法示例:

```javascript
const descopeWcEle = document.getElementsByTagName('descope-wc')[0];
descopeWcEle.addEventListener('error', (e) => alert(`Error! - ${e.detail.errorMessage}`));
```

### `success` - 流量成功完成后发射。 事件细节包含流结果.

用法示例:

```javascript
const descopeWcEle = document.getElementsByTagName('descope-wc')[0];
descopeWcEle.addEventListener('success', (e) => alert(`Success! - ${JSON.stringify(e.detail)}`));
```

### `ready` - 页面准备好了就开火.

此事件对在装入页面前显示/ 隐藏装入指示有用 . 注意:如果流量涉及重定向到过程的非初始阶段,例如与Magic Link或OAuth,此事件也会被发送.

用法示例:

```javascript
const descopeWcEle = document.getElementsByTagName('descope-wc')[0];
descopeWcEle.addEventListener('ready', () => {
  // Remove/hide the loading indication
});
```

## 常见问题

### @descope/web-component 是什么？

望远镜WC

### 如何安装 @descope/web-component？

在项目目录运行 npm install @descope/web-component，或使用 pnpm add / yarn add / bun add。

### @descope/web-component 支持 TypeScript 吗？

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

### @descope/web-component 支持 ESM 还是 CommonJS？

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

### @descope/web-component 可以商用吗？

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

### @descope/web-component 的下载量有多少？

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

### @descope/web-component 还在维护吗？

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