@divkitframework/divkit

中文文档

33.11.0发布于 2026/11/09Apache-2.0TypeScriptESM + CJS零依赖近 30 天下载 1.5万

网络 DivKit

文档目录18 节

网络 DivKit
安装
使用量
内置 CSS
包含js
是否有服务器侧渲染( SSR) , 还是只放在客户端上 ?
您要使用 ES 模块还是普通JS 模块 ?
在浏览器中通过全局变量使用而不构建 :
使用反应
类型脚本和类型
浏览器/节点.js支持
API: 渲染
扩展
所有组件的扩展
自定义组件
调色板支持
API: 其他
关于64位整数的说明

网络 DivKit

安装

npm i @divkitframework/divkit --save

使用量

实例使用重置

内置 CSS

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

包含js

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

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

SSR + 水分

在服务器一侧 /server 模块 :

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

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

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

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。。。 .

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模块可以在浏览器中直接使用而无需构建,但强烈鼓励构建:

<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>

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

<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。它现在已贬值,不应使用.

使用反应

有一个单独的套装.

反应组件包

类型脚本和类型

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

浏览器/节点.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。。。 .

错误

功能,可选.

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

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) (中文(简体) ).

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

海关总署

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

功能,可选.

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

function onCustomAction(action: Action): void {
}

类型面

功能,可选.

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

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

获取 Init

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

函数或对象,可选 .

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

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

或者说

fetchInit: {
    credentials: 'include'
}

投递

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

功能,可选.

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

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树,标记名称,事件或东西,都是你自己的风险.

启用内置扩展

新建扩建工程

所有组件的扩展

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

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

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视频等.

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

存储

对象,可选.

额外的外部存储. 这个 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 带有光和暗主题颜色的属性 :

{
    "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"
            }
        ]
    }
}

主题可随时更改:

instance.setTheme('dark');

API: 其他

变量

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 卡 :

instance.setData({
    ...
});

一些说明:

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

关于64位整数的说明

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

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

文档。。。 . 中等辅导。。。 . Habr 教程。。。 .

电报 : 英语聊天 | {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}你觉得呢。。。 .

版本与发布记录

@divkitframework/divkit 共发布 437 个版本，首次发布于 2022/08/26；过去 12 个月发布了 75 个版本。

版本	发布日期	距今
`33.11.0`latest	2026/11/09	2 天前
`33.10.0-canary-0a27c8fe92183dc935615402bf1ce542a1887e41`canary	2026/11/04	8 天前
`33.10.0`	2026/11/02	9 天前
`33.10.0-canary-408a3da173bc98ff2bb545f269bcfe40b7e29906`	2026/10/31	12 天前
`33.10.0-canary-780977f65c1f0cb839337032501c451c65eb11f7`	2026/10/31	12 天前
`33.9.0`	2026/10/27	15 天前

关于 @divkitframework/divkit 的常见问题