# @divkitframework/divkit 中文文档

规范地址：https://npmcn.com/package/%40divkitframework/divkit/

版本：33\.11\.0
npm 元数据更新时间：2026-11-09T14:45:14.659Z
中文译文更新时间：2026-11-12T11:51:22.591Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：24 MB，39 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-08-25T23:19:22.045Z
- 最新版本发布：2026-11-09T14:45:14.466Z
- 近 30 天下载量：15431（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：437（近 12 个月 75 个）

## 中文简介

网络 DivKit

## 安装

```sh
npm install @divkitframework/divkit
```

也可以使用：`pnpm add @divkitframework/divkit`、`yarn add @divkitframework/divkit`、`bun add @divkitframework/divkit`

## README

## 网络 DivKit

![client code size](https://img.shields.io/badge/client%20lib%20minified&brotli-82.8%20KB-brightgreen)

### 安装

```
npm i @divkitframework/divkit --save
```

### 使用量

[实例使用重置](https://npmcn.com/package/%40divkitframework/divkit-examples)

### 内置 CSS

> \[大 用于所有变体的 Css 文件 `dist/client.css` 需要时间。 以任何方式包含它(导入为模块,在html中直接链接等).

### 包含js

JS代码可以与各种策略相配合. 基本上你需要回答几个问题

### 是否有服务器侧渲染( SSR) , 还是只放在客户端上 ?

#### SSR + 水分

在服务器一侧 `/server` 模块 :

```js
import {render} from '@divkitframework/divkit/server';

const html = render({
    id: 'smth',
    json: {
        card: {},
        templates: {}
    },
    onError(details) {
        console.error(details.error);
    }
});
```

然后使用 `/client-hydratable` 用于水合服务器侧html的客户端:

```js
import {render} from '@divkitframework/divkit/client-hydratable';

render({
    id: 'smth',
    target: document.querySelector('#root'),
    hydrate: true,
    json: {
        card: {},
        templates: {}
    },
    onError(details) {
        console.error(details.error);
    }
});
```

#### 仅限客户端渲染

仅供客户使用 `/client` 模块。 此模块的大小略小于 `/client-hydratable`。 。 。 .

```js
import {render} from '@divkitframework/divkit/client';

render({
    id: 'smth',
    target: document.querySelector('#root'),
    json: {
        card: {},
        templates: {}
    },
    onError(details) {
        console.error(details.error);
    }
});
```

### 您要使用 ES 模块还是普通JS 模块 ?

包裹中包含两人.

节点.js会自动使用相应的版本.

Webpack或其他捆绑将使用ES模块版本.

对于直接通用JS的使用,此文件可以被使用:

```
dist/client.js
dist/client-hydratable.js
dist/server.js
```

ES 模块文件 :

```
dist/esm/client.mjs
dist/esm/client-hydratable.mjs
dist/esm/server.mjs
```

ES模块可以在浏览器中直接使用而无需构建,但强烈鼓励构建:

```html
<script type="module">
    import {render} from './node_modules/@divkitframework/divkit/dist/esm/client.mjs';

    render({
        id: 'smth',
        target: document.querySelector('#root'),
        json: {
            card: {},
            templates: {}
        },
        onError(details) {
            console.error(details.error);
        }
    });
</script>
```

### 在浏览器中通过全局变量使用而不构建 :

```html
<script src="./node_modules/@divkitframework/divkit/dist/browser/client.js"></script>
<script>
    window.Ya.DivKit.render({
        id: 'smth',
        target: document.querySelector('#root'),
        json: {
            card: {},
            templates: {}
        },
        onError(details) {
            console.error(details.error);
        }
    });
</script>
```

> \[大 DivKit 的旧版本使用语法 `Ya.Divkit`。它现在已贬值,不应使用.

### 使用反应

有一个单独的套装.

[反应组件包](https://npmcn.com/package/%40divkitframework/divkit-react)

### 类型脚本和类型

所有模块都有打字符定义(客户端,客户端-可水文和服务器),因此打字符会随时加载.

### 浏览器/节点.js支持

浏览器支持

```
chrome >= 67
safari >= 14
firefox >= 68
```

然而,一些罕见的功能需要更现代化的浏览器,例如, `aspect` (单位:千美元) `container` 需求 `aspect-ratio` 支持在css。 文件说明了这些要求.

节点.js

```
Node.js >= 14
```

### API: 渲染

所有3个导出模块都有导出函数 `render`。此函数在客户端和服务器上以类似方式运行.

`/client` 财务报告和审定财务报表 `/client-hydratable` 需要选项 `target` - 用于渲染json的HTML元素.

相反, `/server` 模块将返回 HTML 字符串.

#### 编号

字符串,必须的.

表示唯一的块标识符. 用来生成ID和类. 不应该有2个街区 `id` 在页面上.

#### 乔森

对象,需要.

迪维森自己.

#### 目标

`/client` 财务报告和审定财务报表 `/client-hydratable`

HTML 元素, 需要 .

#### 水合盐

`/client-hydratable`

布尔,可选的.

这一定是 `true`,如果当前渲染必须将html水合为 `target`。 。 。 .

#### 错误

功能,可选.

召回错误和警告以进行手动处理.

```ts
function onError(detauls: {
    error: Error & {
        level: 'error' | 'warn';
        additional: Record<string, unknown>;
    };
}) {
    console.log(error.level, error.additional, error.message);
}
```

#### 数据

`/client` 财务报告和审定财务报表 `/client-hydratable`

功能,可选.

用于记录点击(用于元素 `action`和能见度记录(适用于具有 `visibility_action(s)` 财务报告和审定财务报表 `disappear_actions`) (中文(简体) ).

```ts
function onStat(details: {
    type: 'click' | 'visible' | 'disappear' | 'trigger';
    action: Action | VisibilityAction | DisappearAction;
}) {
}
```

#### 海关总署

`/client` 财务报告和审定财务报表 `/client-hydratable`

功能,可选.

召回包含非标准协议的组件 .

```ts
function onCustomAction(action: Action): void {
}
```

#### 类型面

功能,可选.

调用自定义 `font-family` css 属性值.

```ts
function typefaceProvider(fontFamily: string, opts?: {
    fontWeight?: number;
}): string {
}
```

#### 获取 Init

`/client` 财务报告和审定财务报表 `/client-hydratable`

函数或对象,可选 .

它被用作第二个参数 `fetch` 请求 `download` 财务报告和审定财务报表 `submit` 行动.

```ts
function fetchInit(url: string) {
    return {
        credentials: 'include'
    };
}
```

或者说

```ts
fetchInit: {
    credentials: 'include'
}
```

#### 投递

`/client` 财务报告和审定财务报表 `/client-hydratable`

功能,可选.

它用来处理 `submit` 行动。 如果它没有被指定, `fetch()` 默认使用.

```ts
function onSubmit(action: ActionSubmit, values: Record<string, unknown>): Promise<void> {
    return fetch(action.reqeust.url, {
        body: JSON.stringify(values)
    });
}
```

#### 平台

`desktop` | `touch` | `auto`

默认值为 `auto`. 为鼠标或触摸事件而调整.

#### 方向

`ltr` | `rtl`

默认值为 `ltr`。这将设定文字的方向和标记内的布局(html) `dir` 属性)。 此属性改变 `start` 编号 : `end` 其他财产和价值.

#### 组合

弦,可选.

根元素中增加了一个类.

#### 定制

对象,可选.

目前支持的属性 :

-   `galleryLeftClass` – 桌面上的左滚动按钮类
-   `galleryRightClass` – 桌面上的右滚动按钮类
-   `pagerLeftClass` —— 用于寻呼器的桌面上左滚动按钮类
-   `pagerRightClass` — 用于调用器的桌面右滚动按钮类
-   `menuPopupClass` 菜单弹出课
-   `menuItemClass` —菜单项的类

#### 内建协议

字符串阵列,可选. 默认值是 `['http', 'https', 'tel', 'mailto', 'intent']`

清单上含有协议的动作组件将作为 `<a>`,然后点击它们将由浏览器处理。 列表以外的协议会让元素以类似按钮的方式被渲染出来,并点击它们就会产生"关于海关行动的".

#### 工具提示旋转

`/client` 财务报告和审定财务报表 `/client-hydratable`

HTML Element, 可选.

允许将工具提示和菜单附加到自定义根中, 在 `target`用于避免收割.

### 扩展

`Map<string, DivExtensionClass>`,可选.

通过自定义代码修改组件行为。 DivKit 包含多个内置扩展名, 此属性可启用 .

扩展仅为客户端 。 人们可以在服务器上制造出一些json,而不是在具有扩展功能的客户端上进行水合,但如果这些扩展功能修改了组件外观,用户可能会在页面负载上注意到这个变化.

也注意新的发布(即使是小版本和补丁版)。 内建的扩展将保持与新代码相容,但自定义的扩展可以与之相撞. 简单的解脱,比如在DOM-node的组件上设置属性,不太可能破碎,但一个更重的属性,它取决于DOM树,标记名称,事件或东西,都是你自己的风险.

[启用内置扩展](https://npmcn.com/package/%40divkitframework/divkit-examples/extensions-builtin/)

[新建扩建工程](https://npmcn.com/package/%40divkitframework/divkit-examples/extensions-handmade/)

### 所有组件的扩展

`DivExtensionRegistration[]`默认为 `[]`。每个条目为 `DivExtensionClass` 或者说 `{ Extension: DivExtensionClass, params?: object, id?: string }`。 。 。 .

将每个扩展应用到每个不包含 `extensions` 进入JSON。 使用同样的 `DivExtension` 接口为 `extensions`:为每个组件 DOM 节点创建单独的实例,登记为 `params` 对象直接传递到它的构造器。 未注册的类别和注册 `params` 接收空对象。 参数是主机提供的值; DivKit 不评价其中的JSON表达式. 喜欢 `extensions`,此选项仅是客户端.

```js
render({
    target,
    id: 'card',
    json,
    extensionsForAllComponents: [
        HoverNotifier,
        { Extension: HoverNotifier, params: { label: 'debug' } }
    ]
});
```

接收 `extension_action`,提供 `id` 登记和执行 `handleAction`行动 `extension_id` 选择该注册,以及 `div_id` 选择组件;不需要 JSON 扩展声明。 无登记 `id` 仍然收到生命周期召回,但无法通过行动加以解决。 对于共享的ID,JSON扩展处理器先运行,然后由来自 `extensionsForAllComponents` 按登记顺序,当处理器返回时停止 `true` (包括等待的结果).

### 自定义组件

`Map<string, CustomComponentDescription>`,可选.

自定义组件可以使用 `customComponents` 地图。 这种结构将名字从json标记到html自定义元素(或网络组件).

这些组件可以提供您应用程序需要的任何附加功能,如地图部件,融入社交网络,YouTube视频等.

自定义组件不仅在客户端得到支持,在服务器端也得到支持. 详情见以下例子:

[简单的自定义组件](https://npmcn.com/package/%40divkitframework/divkit-examples/custom-simple/)

[带有 DivKit 项的自定义组件](https://npmcn.com/package/%40divkitframework/divkit-examples/custom-container/)

[自定义组件和安全部门改革](https://npmcn.com/package/%40divkitframework/divkit-examples/custom-ssr/)

[自定义组件扩展 api](https://npmcn.com/package/%40divkitframework/divkit-examples/custom-extended-api/)

#### 存储

对象,可选.

额外的外部存储. 这个 `get` 财务报告和审定财务报表 `set` 应执行各种方法.

请注意,这些方法必须是同步的! DivKit没有同步渲染方法,所以任何 `get` 函数不能为同步。 可以处理 `set` 同步,但如果值来自 `get` 对你很关键 无法同步读取 你必须在打电话前读取 `render`。 。 。 .

#### 周日开始日

数字,可选的。 默认为0.

影响日期的格式.

#### 寻呼器 儿童已启用

布尔,可选的. `true` 默认.

是否启用裁剪 `pager` 要素。 在有"影子"元素的情况下,它可以有用.

#### 调用程序

布尔,可选的. `true` 默认.

是否拖动 `pager` 启用或不启用带有鼠标的元素.

#### 视频显示器

对象,可选.

一个执行自定义视频播放器的提供者. 在服务器一侧 `videoPlayerProvider` 必须包含 `template` 属性,是视频播放器的字符串或标记提供者功能。 在客户方面 `videoPlayerProvider` 必须包含 `instance` 函数创建玩家实例.

#### 主题

`system` | `light` | `dark`

默认值为 `system`中的变量 `palette` 编辑 `themeVariableName` 变量.

#### 可变主题Name

弦,可选.

设定时, 此属性会创建一个可存储当前主题的变量( W)`light` 或者说 `dark`) (中文(简体) ).

### 调色板支持

未来将去除这一特征.

迪维克森和 `card` 财务报告和审定财务报表 `templates` 可包含一个 `palette` 带有光和暗主题颜色的属性 :

```json
{
    "card": {
        "states": [
            {
                "div": {
                    "type": "text",
                    "text": "Hello palette",
                    "text_color": "@{text}",
                    "background": [{
                        "type": "solid",
                        "color": "@{bg}"
                    }]
                },
                "state_id": 0
            }
        ],
        "log_id": "test"
    },
    "templates": {},
    "palette": {
        "dark": [
            {
                "name": "bg",
                "color": "#000"
            },
            {
                "name": "text",
                "color": "#fff"
            }
        ],
        "light": [
            {
                "name": "bg",
                "color": "#fff"
            },
            {
                "name": "text",
                "color": "#000"
            }
        ]
    }
}
```

主题可随时更改:

```js
instance.setTheme('dark');
```

### API: 其他

#### 变量

```js
import {createVariable, createGlobalVariablesController, render} from '@divkitframework/divkit';

// Custom variable outside of DivJson
const variable = createVariable('name', 'string', 'val');

variable.subscribe(newVal => {
    console.log(newVal);
});

// Custom scope for variables
const controller = createGlobalVariablesController();

controller.setVariable(variable);

render(({
    id: 'smth',
    target: document.querySelector('#root'),
    json: {},
    globalVariablesController: controller
});
```

#### 设置数据( 警告)

通过这种方法,您可以快速地重新绘制 DivKit 卡 :

```ts
instance.setData({
    ...
});
```

一些说明:

-   这种方法是实验性的,它的逻辑和api可能会被改变未来的版本.
-   `setData` 不改变任何现有的变量或可变触发。 它将创造新的变量。 这是故意的.
-   这种方法将尽量少做活,并试图保持卡的状态(输入值等).

### 关于64位整数的说明

DivKit 内部使用 `BigInt` 类型,如果当前平台支持它(无论是客户端还是服务器端)。 这意味着在不支持的平台上,如果值超过2^53,整数会失去精度.

注意内置功能如 `JSON.parse` 财务报告和审定财务报表 `.json()` 将解析大值,但结果类型将是 `number`没有 `bigint`。因此,例如,如果有人从服务器获取数据,数值可能会失去准确性 _外部_ divKit图书馆.

* * *

[文档](https://divkit.tech/doc)。 。 。 . [中等辅导](https://medium.com/p/cad519252f0f)。 。 。 . [Habr 教程](https://habr.com/ru/company/yandex/blog/683886/)。 。 。 .

电报 : [英语聊天](https://t.me/divkit_community_en) | [{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢](https://t.me/divkit_community_ru)。 。 。 .

## 常见问题

### @divkitframework/divkit 是什么？

网络 DivKit

### 如何安装 @divkitframework/divkit？

在项目目录运行 npm install @divkitframework/divkit，或使用 pnpm add / yarn add / bun add。

### @divkitframework/divkit 支持 TypeScript 吗？

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

### @divkitframework/divkit 支持 ESM 还是 CommonJS？

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

### @divkitframework/divkit 可以商用吗？

@divkitframework/divkit 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @divkitframework/divkit 的下载量有多少？

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

### @divkitframework/divkit 还在维护吗？

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