Ym-downloader NPM

ym-downloader

ym-downloader是一个面向yimian图表下载需求的通用下载器，它能帮助开发者快速将web端的图表数据下载成excel文件或包含excel文件、网页快照的zip包

🚀 Features

支持在生成的excel表格主体上方添加信息
支持生成多sheets的excel文件
支持对numbers进行多种类型的格式化
支持在生成的网页快照中剔除部分html节点
处理在生成网页快照中与yimian使用的svg-sprite产生的技术冲突

📦 Install

该包不依赖任何框架

npm i ym-downloader

🦄 Usage

import { ymDownload, DownLoadConfig, ColumnsConfig } from 'ym-downloader'

// drinks
const drinks: Array<object> = [
  { product: 'tea', count: 119500, buzz_growth_ratio: 4.5412, avg_price: 6.2499 },
  { product: 'coke', count: 2255000, buzz_growth_ratio: 0.2124, avg_price: 3.5050 },
  { product: 'coffe', count: 12542988, buzz_growth_ratio: 103.8041, avg_price: 15.4073 },
  { product: 'water', count: 801248500, buzz_growth_ratio: 0.0141, avg_price: 2.1034 },
]
const drinksColumnsConfig: ColumnsConfig = [
  { name: '饮料名称', field: 'product', valueType: 'string' },
  { name: '销量', field: 'count', valueType: 'integer' },
  { name: '销量增长率', field: 'count_growth_ratio', valueType: 'percentage' },
  { name: '平均售价', field: 'avg_price', valueType: 'float' },
]

// foods
const foods: Array<object> = [
  { product: 'beef', count: 119500, buzz_growth_ratio: 4.5412, avg_price: 6.2499 },
  { product: 'chicken', count: 2255000, buzz_growth_ratio: 0.2124, avg_price: 3.5050 },
  { product: 'banana', count: 12542988, buzz_growth_ratio: 103.8041, avg_price: 15.4073 },
  { product: 'apple', count: 801248500, buzz_growth_ratio: 0.0141, avg_price: 2.1034 },
]
const foodsColumnsConfig: ColumnsConfig = [
  { name: '食物名称', field: 'product', valueType: 'string' },
  { name: '销量', field: 'count', valueType: 'integer' },
  { name: '销量增长率', field: 'count_growth_ratio', valueType: 'percentage' },
  { name: '平均售价', field: 'avg_price', valueType: 'float' },
]

// 1. 单sheet下载
ymDownload({
  fileName: '饮料数据',
  columnsConfigs: [drinksColumnsConfig],
  fileContents: [drinks],
  sheetNames: ['sheet1'],
  sheetInfos: [[
    'Powered by YiTrend: https://yirend.yimian.com.cn',
    'Date: 2022.01.01',
    'Producer: Dolly',
  ]]
})
.then(() => console.log('success'))
.catch(() => console.log('failed'))
.finally(() => { console.log('done'))

// 2. 多sheets下载
ymDownload({
  fileName: '综合数据',
  columnsConfigs: [
    drinksColumnsConfig,
    foodsColumnsConfig,
  ],
  fileContents: [
    drinks,
    foods,
  ],
  sheetNames: [
    '饮料数据',
    '食物数据'
  ],
  sheetInfos: [
    ['This is drinks data'],
    ['This is foods data'],
  ]
})

// 3. excel & 快照 zip 包下载
const node = window.querySelector('.test-element')
ymDownload({
  fileName: '饮料数据',
  columnsConfigs: [drinksColumnsConfig],
  fileContents: [drinks],
  htmlElement: node,
})

下载后的excel样例：

download-demo

📥 Params

interface ColumnsConfig {
  // 列名
  name: string
  
  // 该列取何字段
  field: string
  
  // 该列数据类型，格式化方案与YiTrend, YiDrone对齐，参看源码
  valueType?: 'string' | 'integer' | 'float' | 'percentage'
  
  // 不想使用包提供的四种格式化方式，可传入微软支持的格式化字符串
  // https://www.ablebits.com/office-addins-blog/2016/07/07/custom-excel-number-format/#Understanding-Excel-number
  customerFormat?: string
}


interface DownloadConfig {
  // 文件名
  fileName: string
  
  // sheets的列配置数组
  columnsConfigs: Array<ColumnsConfig>
  
  // sheets的数据数组
  fileContents?: Array<Array<object>>
  
  // 远程获取数据的函数（与fileContents之间必须传入一个, 否则报错)
  getRemoteData?: () => Promise<Array<Array<object>>>
  
  // sheets的名称，默认自增sheet1, sheet2...
  sheetNames?: Array<string>
  
  // sheets的表头信息
  sheetInfos?: Array<Array<string>>
  
  // 快照的html对象
  htmlElement?: HTMLElement
  
  // 在快照中不需要被渲染的节点所包含的className，默认值['ym-downloader-image-no-render']
  excludeClassName?: Array<string>
  
  // 若产品中使用了svg-sprites技术，在快照节点中svg引用需绑定svgClassName才能被正常渲染，默认值'ym-svg'
  svgClassName?: string
}