Checkboxland

将任何内容渲染为 HTML 复选框

示例演示

（在此查看演示源代码）

社区示例：

（如果你有示例想要分享，请创建一个文档 PR并添加到上面的列表中）

概览

Checkboxland 是一个用于将任何内容渲染为 HTML 复选框的 JavaScript 库。

你可以用它来展示动画、文字、图片、视频以及任意数据。它还支持插件，因此你可以添加自己的 API。

Checkboxland 无依赖、框架无关，而且很有趣！🙃

为什么这个项目会存在？这里有相关背景介绍。

局限性

网页上存在大量元素可能会影响运行时性能。复选框也不例外。Checkboxland 试图缓解其中一些问题，但如果你显示大型网格（1500+ 复选框）并尝试快速更新它们，仍可能会遇到性能问题。

为获得最佳效果，请将复选框数量保持在 1500 个以下。一些推荐的尺寸包括 32x32、48x24 和 64x16。

安装配置

通过 npm 安装此包：

npm install checkboxland

将其导入你的应用程序，并创建一个复选框网格：

import { Checkboxland } from 'checkboxland';

// 在 #my-container 内创建一个 16x16 的复选框网格
const cbl = new Checkboxland({
  dimensions: '16x16',
  selector: '#my-container'
});

Checkboxland 类接受以下几个参数：

注意：如果你确实想通过 <script> 标签加载 Checkboxland，可以考虑使用内联 ES6 模块，如下所示：

<script type="module">
  import { Checkboxland } from 'https://unpkg.com/checkboxland?module';
  window.Checkboxland = Checkboxland;
</script>

一个例子

让我们在复选框网格上展示一颗爱心：

import { Checkboxland } from 'checkboxland';

const cbl = new Checkboxland({
  dimensions: '8x7',
  selector: '#my-container'
});

// 创建爱心的数据表示
const heart = [
  [0,1,1,0,0,1,1,0],
  [1,0,0,1,1,0,0,1],
  [1,0,0,0,0,0,0,1],
  [1,0,0,0,0,0,0,1],
  [0,1,0,0,0,0,1,0],
  [0,0,1,0,0,1,0,0],
  [0,0,0,1,1,0,0,0],
];

// 使用我们提供的数据更新网格
cbl.setData(heart);

（注意：你可以在 Codepen上尝试这个示例，然后 Fork 它来创建你自己的演示）

一组显示爱心形状的复选框网格

发生了什么？

我们创建了一个 JavaScript 矩阵（数组的数组）来表示网格。矩阵中的每个位置代表一个复选框，其中：

通过将这个矩阵传递给 setData() 方法，我们可以更新页面上的复选框网格。

更多 Checkboxland 示例

更多关于复选框网格交互方式的内容，请参见下面的 API 方法。

底层 API

底层 API 允许你使用原始数据更新复选框网格。

getCheckboxValue

获取复选框网格中单个复选框的值。

需要一个 (x, y) 坐标来指定复选框的位置。

注意：网格左上角为坐标原点 (0,0)。

.getCheckboxValue(x, y)

参数

返回值

（数字）：返回 0、1 或 2（0 表示"未选中"，1 表示"选中"，2 表示"不确定"）。

setCheckboxValue

设置复选框网格中单个复选框的值。

需要一个 (x, y) 坐标来指定复选框的位置。

注意：网格左上角为坐标原点 (0,0)。

.setCheckboxValue(x, y, newValue)

参数

返回值

无

getData

获取表示复选框网格当前状态的数据矩阵。

.getData()

参数

无

返回值

（数组）：一个矩阵（数组的数组），表示复选框网格的完整状态。

setData

将复选框网格的值设置为所提供的矩阵中的值。

默认情况下，矩阵会从左上角开始覆盖网格中已有的数据。可以通过选项进行更精确的数据设置。

.setData(data, [options])

参数

返回值

无

clearData

清除复选框网格中的所有数据。结果：网格中所有复选框变为未选中状态。

.clearData()

参数

无

返回值

无

getEmptyMatrix

一个工具方法，返回一个与现有复选框网格尺寸相同的空矩阵。

可选地，可以传入一个对象来自定义预填充值或返回矩阵的尺寸。

.getEmptyMatrix([options])

参数

返回值

（数组）：一个矩阵（数组的数组），具有与现有复选框网格相同的尺寸，仅包含 0 值（除非另有指定）。

扩展 API

Checkboxland 内置了插件，通过更高级的功能扩展 API。以下是这些"核心"插件提供的 API 方法。

print

将文字打印到复选框网格上。这些文字会从左上角开始覆盖现有的复选框网格。

默认字体中的大多数字符大小为 5x7 个复选框。支持的字符包括：

ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
0123456789`~!@#$%^&*()-_+=[]{}|\/;:"',.<>?

实际示例请参见文本框演示。

.print(text, [options])

无，除非 options.dataOnly 设置为 true。在这种情况下，返回一个矩阵（数组的数组）。

marquee

通过让数据块从右向左滚动穿过复选框网格来实现动画效果。

实际示例请参见跑马灯演示。

.marquee(data, [options])

参数

返回值

无

清理

要取消正在进行的跑马灯动画，请调用 cleanUp 方法：

.marquee.cleanUp()

renderImage

将提供的图片渲染为复选框。已测试的格式包括 PNG、JPEG、WEBP 和 GIF（非动画）。

注意：使用 HTMLImageElement 从外部域名加载图片时，需要包含 crossorigin="anonymous" 属性。图片服务器还需要发送 Access-Control-Allow-Origin 响应头。

参见使用 HTMLImageElement、文件上传、URL 加载和拖放的示例。

.renderImage(dataSource, [options])

参数

返回值

无

renderVideo

将提供的视频渲染为复选框。已测试的格式包括 MP4、WEBM 和 MediaStreams。

注意：使用 HTMLVideoElement 从外部域名加载视频时，需要包含 crossorigin="anonymous" 属性。视频服务器还需要发送 Access-Control-Allow-Origin 响应头。

参见使用 HTMLVideoElement、文件上传、URL 加载、拖放以及摄像头的示例。

.renderVideo(dataSource, [options])

参数

返回值

无

清理

要取消自动播放的复选框视频，请调用 cleanUp 方法：

.renderVideo.cleanUp()

transitionWipe

通过在屏幕上擦除的方式，在当前复选框网格状态和未来状态之间进行过渡动画。

实际示例请参见擦除过渡演示。

.transitionWipe(newData, [options])

参数

返回值

无

清理

要取消正在进行的过渡动画，请调用 cleanUp 方法：

.transitionWipe.cleanUp()

dataUtils

对数据矩阵执行各种转换（或操作）并返回结果。这些转换不会影响复选框网格。

.dataUtils(actionName, matrix, [options])

参数

支持的 actionName：

返回值

（数组）：一个矩阵（数组的数组），表示转换后的数据。

onClick

注册一个 eventHandler，当复选框网格被点击时调用。同时提供有关点击位置的 data。

实际示例请参见"点击事件"演示。

.onClick(eventHandler)

参数

调用时，eventHandler 会接收到一个 data 对象，定义如下：

返回值

无

清理

要从复选框网格中移除 onClick 事件监听器，请调用 cleanUp 方法：

.onClick.cleanUp()

使用插件

Checkboxland 支持插件，可以扩展 API 并提供更高级的功能。

这是一个（ realistic 但虚构的）使用插件扩展 Checkboxland 的示例：

import { Checkboxland } from 'checkboxland';
import mirrorPlugin from 'checkboxland-mirror';

Checkboxland.extend(mirrorPlugin);

const cbl = new Checkboxland();

// 镜像网格上的数据
cbl.mirror();

你可以在 Checkboxland 核心文件中看到更多使用插件的示例。

现有插件

（如果你为 Checkboxland 编写了第三方插件，我会将其列在这里）

创建插件

Checkboxland 插件是能够访问 Checkboxland 特殊数据的 JavaScript 函数。

插件可以通过 this 对象访问 Checkboxland 的所有属性和底层 API 方法。包括：

示例

下面是一个插件示例，它将各种数据记录到 JavaScript 控制台：

import { Checkboxland } from 'checkboxland';

// 定义插件名称和要执行的函数
const myPlugin = {
  name: 'logData',
  exec: (propertyName) => {
    if (propertyName === 'element') {
      console.log(this.displayEl);
    } else
    if (propertyName === 'dimensions') {
      console.log(`width: ${this.dimensions[0]}`);
      console.log(`height: ${this.dimensions[1]}`);
    } else
    if (propertyName === 'matrix') {
      console.log(this.getData());
    }
  }
  cleanUp: () => {
    // 可选的清理方法，在使用完插件时调用
    // （用于移除事件监听器、清除定时器等）
    console.log('clean up was called');
  }
}

// 注册插件
Checkboxland.extend(myPlugin);

const cbl = new Checkboxland({ dimensions: '4x2' });

// 通过插件名称调用插件函数
cbl.logData('element'); // => <div id="checkboxland">...</div>
cbl.logData('dimensions'); // => 'width: 4, height: 2'
cbl.logData('matrix'); // => (2) [Array(4), Array(4)]
cbl.logData.cleanUp(); // => 'clean up was called'

更多插件示例请参见Checkboxland 内置的这些插件。

Made with at the Recurse Center