dataset-config

从 HTML data-* 属性中提取配置，并自动转换为 JavaScript 对象。

遵循浏览器原生 HTMLElement.dataset 规范，同时提供一些有用的额外功能。

例如：

<div data-toggle="tooltip" data-delay="300" data-placement="top"></div>

无需额外 JSON 配置：

{
  toggle: "tooltip",
  delay: 300,
  placement: "top"
}

特性

• 🚀 零依赖
• 📦 极小体积（minified + brotli ≤ 0.6KB）
• ✅ 自动类型转换
• ✅ 点语法对象解析
• ✅ 前缀过滤
• ✅ 配置排除
• ✅ 全局函数解析

Why dataset-config?

如果你正在开发一个支持 data-* 初始化的 JavaScript 插件，你通常需要处理：

• dataset 默认只能得到字符串
• "true"、"300" 需要手动转换类型
• JSON 配置需要手动解析
• data-a.b.c 需要转换成嵌套对象
• 多个插件之间需要处理配置隔离

于是每个插件都会重复编写类似的逻辑。

dataset-config 将这些通用能力集中处理：

例如：

<div data-delay="300" data-position.x="100" data-position.y="200" data-draggable="true"></div>

自动转换为：

{
  delay: 300,
  position: {
    x: 100,
    y: 200
  },
  draggable: true
}

让你的插件只关注业务逻辑：

new Plugin(element, datasetConfig(element));

dataset-config 的目的：

把每个插件都会需要的 data-* 解析逻辑抽离成一个独立、小巧、可复用的基础库（类似于 lilconfig 和 cosmiconfig 对配置文件解析所做的事情），避免每个插件重复实现 data 属性解析。

安装

npm

npm install dataset-config

CDN

<script src="https://unpkg.com/dataset-config@latest/dist/dataset-config.min.js"></script>

基础使用

HTML:

<div id="demo" data-name="hello" data-count="10"></div>

JavaScript:

import datasetConfig from "dataset-config";

const config = datasetConfig(document.querySelector("#demo"));

console.log(config);

结果：

{
  name: "hello",
  count: 10
}

自动类型解析

dataset-config 会自动转换常见类型。

Boolean

HTML:

<div data-visible="true" data-disabled="false"></div>

结果：

{
  visible: true,
  disabled: false
}

Number

HTML:

<div data-width="100" data-offset="-20" data-scale="1.5"></div>

结果：

{
  width: 100,
  offset: -20,
  scale: 1.5
}

JSON Object

HTML:

<div data-user='{"name":"Tom"}'></div>

结果：

{
  user: {
    name: "Tom";
  }
}

JSON Array

HTML:

<div data-items="[1,2,3]"></div>

结果：

{
  items: [1, 2, 3];
}

非法 JSON

如果 JSON 解析失败，会保持原字符串：

HTML:

<div data-value="{foo}"></div>

结果：

{
  value: "{foo}";
}

点语法对象解析

支持使用 . 创建无限层级对象。

HTML:

<div data-position.x="100" data-position.y="200"></div>

结果：

{
  position: {
    x: 100,
    y: 200
  }
}

更深层：

HTML:

<div data-style.color.primary="red"></div>

结果：

{
  style: {
    color: {
      primary: "red";
    }
  }
}

kebab-case 自动转换

HTML:

<div data-scroll-top-offset="200"></div>

结果：

{
  scrollTopOffset: 200;
}

等价于：

element.dataset.scrollTopOffset;

前缀过滤 prefix

当页面存在多个插件时，可以使用 prefix 避免配置冲突。

HTML:

<div data-app-scroll-offset="100" data-app-theme="dark" data-other-value="hello"></div>

代码：

datasetConfig(element, {
  prefix: "app",
});

结果：

{
  scrollOffset: 100,
  theme: "dark"
}

不会读取：

data-other-value

支持 kebab-case prefix

以下两种写法等价：

datasetConfig(element, {
  prefix: "app-scroll",
});

或者：

datasetConfig(element, {
  prefix: "appScroll",
});

HTML:

<div data-app-scroll-offset="100"></div>

结果：

{
  offset: 100;
}

排除字段 excludeKeys

有时候希望读取大部分配置，但忽略某些字段。

HTML:

<div data-delay="300" data-theme="dark"></div>

代码：

datasetConfig(element, {
  excludeKeys: ["delay"],
});

结果：

{
  theme: "dark";
}

支持深层排除

HTML:

<div data-config.user.name="Tom" data-config.user.age="18"></div>

代码：

datasetConfig(element, {
  excludeKeys: ["config.user.name"],
});

结果：

{
  config: {
    user: {
      age: 18;
    }
  }
}

排除整个对象

datasetConfig(element, {
  excludeKeys: ["config.user"],
});

结果：

{
  config: {
  }
}

全局函数解析

默认情况下：

parseFunction: true;

dataset-config 会尝试解析全局函数。

HTML:

<div data-on-click="handleClick"></div>

JavaScript:

window.handleClick = function () {
  console.log("clicked");
};

结果：

{
  onClick: window.handleClick;
}

禁用函数解析

datasetConfig(element, {
  parseFunction: false,
});

结果：

{
  onClick: "handleClick";
}

API

datasetConfig(element, options);

参数：

| 参数 | 类型 | 默认值 | 说明 | | ------------- | ----------- | --------- | ---------------- | | element | HTMLElement | - | 需要解析的元素 | | prefix | string | undefined | 只解析指定前缀 | | parseFunction | boolean | true | 是否解析全局函数 | | excludeKeys | string[] | [] | 排除字段 |