[English](./README.md) | 简体中文
[![NPM version][npm-image]][npm-url] [![NPM version][npm-next-image]][npm-url] [![NPM downloads][download-image]][download-url] [![install size][npm-size]][npm-size-url]
[![Test CI status][test-ci]][test-ci-url] ![Deploy CI][deploy-ci] [![Coverage][coverage]][codecov-url]
[![ docs by dumi][dumi-url]](https://d.umijs.org/) [![Build With father][father-url]](https://github.com/umijs/father/)
[![Gitpod ready-to-code][gitpod-badge]][gitpod-url]
[gitpod-badge]: https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod
[gitpod-url]: https://gitpod.io/#https://github.com/ant-design/html2sketch
[dumi-url]: https://img.shields.io/badge/docs%20by-dumi-blue
[father-url]: https://img.shields.io/badge/build%20with-father-028fe4.svg
[npm-image]: http://img.shields.io/npm/v/html2sketch.svg?style=flat-square&color=deepgreen&label=latest
[npm-next-image]: https://img.shields.io/npm/v/html2sketch/next?label=next&style=flat-square
[npm-url]: http://npmjs.org/package/html2sketch
[npm-size]: https://img.shields.io/bundlephobia/minzip/html2sketch?color=deepgreen&label=gizpped%20size&style=flat-square
[npm-size-url]: https://packagephobia.com/result?p=html2sketch
[coverage]: https://codecov.io/gh/ant-design/html2sketch/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/ant-design/html2sketch/branch/master
[test-ci]: https://github.com/ant-design/html2sketch/workflows/Test%20CI/badge.svg
[deploy-ci]: https://github.com/ant-design/html2sketch/workflows/Deploy%20CI/badge.svg
[test-ci-url]: https://github.com/ant-design/html2sketch/actions?query=workflow%3ATest%20CI
[deploy-ci-ci]: https://github.com/ant-design/html2sketch/actions?query=workflow%3ADeploy%20CI
[download-image]: https://img.shields.io/npm/dm/html2sketch.svg?style=flat-square
[download-url]: https://npmjs.org/package/html2sketch
## 简介
一个将 HTML 转 Sketch JSON 的模块
## 快速上手
### 安装
```bash
npm i html2sketch --save
```
或
```
yarn add html2sketch
```
### 使用
`html2sketch` 包含 3 个主要方法 `nodeToLayer` 、 `nodeToGroup` 和 `nodeToSymbol` 。
#### nodeToLayer
将 DOM 节点转成 Sketch 的对象,转换时不处理节点的子级
```js
import { nodeToLayer } from 'html2sketch';
const fn = async () => {
// 1. 获取 DOM 节点
const node = document.getElementById('id');
// 2. 调用转换方法
const layer = await nodeToLayer(node);
// 3. 生成为 Sketch JSON
const sketchJSON = layer.toSketchJSON();
return sketchJSON;
};
fn().then((json) => {
console.log(json);
});
```
#### nodeToGroup
将 DOM 节点以及它的子级整体转成 Sketch 的 Group 对象
```js
import { nodeToGroup } from 'html2sketch';
const fn = async () => {
// 1. 获取 DOM 节点
const node = document.getElementById('id');
// 2. 调用转换方法
const group = await nodeToGroup(node);
// 3. 生成为 Sketch JSON
const sketchJSON = group.toSketchJSON();
return sketchJSON;
};
fn().then((json) => {
console.log(json);
});
```
#### nodeToSymbol
将 DOM 节点转 Sketch 的 Symbol 对象
```js
import { nodeToSymbol } from 'html2sketch';
const fn = async () => {
// 1. 获取 DOM 节点
const node = document.getElementById('id');
// 2. 调用转换方法
const symbol = await nodeToSymbol(node);
// 3. 生成为 Sketch JSON
const sketchJSON = symbol.toSketchJSON();
return sketchJSON;
};
fn().then((json) => {
console.log(json);
});
```
## 有了 Sketch JSON 的下一步?
生成的 Sketch JSON 严格符合 [Sketch File Format](https://developer.sketch.com/file-format/) 结构，因此只需要简单地将相应的 JSON 按照 Sketch 文件规范合成 `.sketch` 文件，即可获得 Sketch 文件。
社区相关 API 模块:
- [sketch-json-api](https://github.com/ant-design/sketch-json-api)
- [node-sketch](https://github.com/oscarotero/node-sketch)
- [sketch-constructor](https://github.com/amzn/sketch-constructor)
如果希望直接使用该 JSON 对象，可以使用 [Sketch JSON](https://github.com/arvinxx/sketch-json) 插件，一键粘贴 JSON 进入 Sketch 中。
## 开发动机
本模块主要的应用领域在于 C2D (Code to Design)。主要参考了 [html-sketchapp](https://github.com/html-sketchapp/html-sketchapp) 。
html-sketchapp 可以直接将任何框架开发的 HTML 页面转换成 Sketch 文档，但是也具有明显的局限性：
- **不支持伪类、文本溢出（overflow）、渐变、transform 等属性**: 这就使得很多网页使用 html-sketchapp 解析出来的视觉还原度不高；
- **html-sketchapp 虽然不依赖框架，但是与 Sketch App 完全耦合.**: 生成的 JSON 并不严格符合 [Sketch File Format](https://developer.sketch.com/file-format/) ，所以无法直接生成 sketch 文档，缺少在服务器端集成的能力。
- **html-sketchapp 基于 js 开发，缺少完善的类型定义，项目架构不太合理，二次开发难度大。**
### html2sketch 做了什么？
html2sketch 在 html-sketchapp 的基础上做了诸多优化，取其精华去其糟粕：
#### 解析能力强化
html2sketch 支持了大部分 html-sketchapp 不支持的网页样式，比如伪类、渐变、文本溢出等等。这一点对于解析效果来说，非常重要。可能原本使用 html-sketchapp 能够还原出 80% 的效果，而在使用 html2sketch 模块之后，可以支持到 95%乃至以上的还原度。当然，模块的解析能力也需要靠解析场景的覆盖来逐步提升，如果在使用当中遇到不正确的解析情况，请务必给我提 [issue](https://github.com/ant-design/html2sketch/issues) ，我会尽快解决。目前该模块支持的样式都在 [解析用例](https://ant-design.github.io/html2sketch/e2e) 中进行了呈现。
#### 与 Sketch App 解耦
html2sketch 这个模块在功能层面最大的差异点，就是与 Sketch App 解耦。相关的解析能力 （Svg、图片、字体等的解析）全都从零开始构建。
由于 html2sketch 生成的 Sketch JSON 将严格符合 [Sketch File Format](https://developer.sketch.com/file-format/) ，所以在获得这个 Sketch JSON 后，就可以直接使用 [sketch-json-api](https://github.com/ant-design/sketch-json-api)、[node-sketch](https://github.com/oscarotero/node-sketch) 等模块合成合法的 sketch 文件，不需要其他任何处理。因此，基于这个模块就可以使用任何普通的服务器解析网页，生成 sketch 文件。
#### 基于 Typescript 开发
html2sketch 采用 Typescript 进行开发，所以无论是作为消费者的使用体验，还是作为生产者的开发体验，都将十分良好。无论是项目的组织结构、代码注释、单元测试上都有一定保证。
## 开发
查看 [开发指南](https://github.com/ant-design/html2sketch/guide)
## License
[MIT](./LICENSE)