README

Holder 使用 SVG 在浏览器中渲染图像占位符。

由成千上万的开源项目（包括 Bootstrap v3）和许多其他网站使用。

无额外请求，包大小小，高度可定制。

安装

npm: npm install holderjs
yarn: yarn add holderjs
unpkg: https://unpkg.com/holderjs
cdnjs: https://cdnjs.com/libraries/holder
jsDelivr: https://www.jsdelivr.com/package/npm/holderjs
Bower: bower install holderjs
Rails Assets: gem 'rails-assets-holderjs'
Meteor: meteor add imsky:holder
Composer: php composer.phar update imsky/holder
NuGet: Install-Package Holder.js

用法

在您的 HTML 中包含 holder.js

<script src="holder.js"></script>

Holder 将处理具有特定 src 属性的所有图像，如下所示

<img src="holder.js/300x200">

上述标签将渲染为宽 300 像素、高 200 像素的占位符。

为了避免控制台 404 错误，您可以使用 data-src 而不是 src。

编程使用

要编程插入占位符，请使用 run() API

var myImage = document.getElementById('myImage');

Holder.run({
  images: myImage
});

占位符选项

占位符选项通过 URL 属性设置，例如 holder.js/300x200?x=y&a=b。多个选项通过 & 字符分隔。

theme: 占位符使用的主题。示例：holder.js/300x200?theme=sky
random: 使用随机主题。示例：holder.js/300x200?random=yes
bg: 背景颜色。示例：holder.js/300x200?bg=2a2025
fg: 前景（文本）颜色。示例：holder.js/300x200?fg=ffffff
text: 自定义文本。示例：holder.js/300x200?text=Hello
size: 自定义文本大小。默认为 pt 单位。示例：holder.js/300x200?size=50
font: 自定义文本字体。示例：holder.js/300x200?font=Helvetica
align: 自定义文本对齐方式（左，右）。示例：holder.js/300x200?align=left
outline: 绘制占位符的轮廓和对角线。示例：holder.js/300x200?outline=yes
lineWrap: 行长度与图像宽度的最大比率。示例：holder.js/300x200?lineWrap=0.5

主题

Holder 支持主题，帮助占位符与您的布局融合。

有 6 个默认主题：sky、vine、lava、gray、industrial 和 social。

自定义主题

主题有5个属性：fg（前景色）、bg（背景色）、size（大小）、font（字体）和fontweight（字体粗细）。size属性指定主题的最小字体大小。fontweight的默认值是bold（粗体）。您可以创建一个如下所示的示例主题：

Holder.addTheme("dark", {
  bg: "#000",
  fg: "#aaa",
  size: 11,
  font: "Monaco",
  fontweight: "normal"
});

如果您有一组占位符，希望使用特定的文本，您可以通过向主题添加text属性来实现：

Holder.addTheme("thumbnail", { bg: "#fff", text: "Thumbnail" });

使用自定义主题

有两种方式可以在Holder中使用自定义主题：

在运行时包含主题以渲染已使用主题名称的占位符
在任何时候包含主题并重新渲染使用主题名称的占位符

第一种方法是最简单的。在包含holder.js之后，添加一个script标签来添加您想要的主题：

<script src="holder.js"></script>
<script>
Holder.addTheme("bright", {
  bg: "white", fg: "gray", size: 12
});
</script>

第二种方法需要在添加主题后调用run，如下所示：

Holder.addTheme("bright", {bg: "white", fg: "gray", size: 12}).run();

在特定图像上使用自定义主题和域名

您可以在不同图像的不同区域使用自定义主题的Holder：

<img data-src="example.com/100x100?theme=simple" id="new">

Holder.run({
  domain: "example.com",
  themes: {
    "simple": {
      bg: "#fff",
      fg: "#000",
      size: 12
    }
  },
  images: "#new"
});

插入具有自定义主题的图像

您可以通过链式调用Holder来程序化地添加占位符：

Holder.addTheme("new", {
  fg: "#ccc",
  bg: "#000",
  size: 10
}).addImage("holder.js/200x100?theme=new", "body").run();

addImage的第一个参数是src属性，第二个是父元素的CSS选择器。

文本

Holder会自动将超出图像边界之外的文本添加换行符。如果文本过长，超出了水平和垂直边界，文本将被移动到顶部。如果您想控制换行，可以在text属性中添加\n：

<img data-src="holder.js/300x200?text=Add \n line breaks \n anywhere.">

如果您想禁用换行，将nowrap选项设置为true：

<img data-src="holder.js/300x200?text=Add \n line breaks \n anywhere.&amp;nowrap=true">

当使用text选项时，图像尺寸不会显示。要将尺寸重新插入到文本中，简单使用特殊占位符holder_dimensions。

<img data-src="holder.js/90px80p?theme=sky&text=Placeholder dimensions: holder_dimensions">

使用自定义字体的占位符默认使用canvas渲染，因为SVG对跨域资源链接有约束。如果您只使用本地可用的字体，您可以在Holder.run选项中将noFontFallback设置为true来禁用此行为。但是，如果您需要使用外部加载的字体来渲染SVG占位符，您必须使用object标签而不是img标签，并给适当的link标签添加holderjs类。以下是一个示例：

<head>
<link href="http://.../font-awesome.css" rel="stylesheet" class="holderjs">
</head>
<body>
<object data-src="holder.js/300x200?font=FontAwesome"></object>

重要：在本地测试时，字体URL必须定义了http或https协议。

重要：从除公共注册表（即Google Fonts、Typekit等）以外的位置提供的字体需要设置正确的CORS头。有关更多详细信息，请参阅如何使用CDN与Web字体。

<object>占位符与<img>占位符类似，其优点是其DOM可以被检查和修改。与<img>占位符一样，data-src属性比data属性更可靠。

流体占位符

重要：百分比使用p字符指定，而不是使用%字符。

使用百分比指定尺寸会创建一个响应媒体查询的流体占位符。

<img data-src="holder.js/100px75?theme=social">

默认情况下，流体占位符将显示其当前尺寸（以像素为单位）。要显示原始尺寸（即100%x75），将textmode标志设置为literal，如下所示：holder.js/100px75?textmode=literal。

自动尺寸占位符

如果您想避免Holder强制设置图像大小，使用auto标志，如下所示：

<img data-src="holder.js/200x200?auto=yes">

这将渲染一个不包含任何嵌入CSS高度的占位符。

要显示自动尺寸占位符的当前尺寸，将textmode标志设置为exact，如下所示：holder.js/200x200?auto=yes&textmode=exact。

防止在窗口大小调整时更新

流体占位符和精确模式的自动尺寸占位符在窗口大小调整时都会更新。要设置特定图像是否在窗口大小调整时更新，可以使用setResizeUpdate方法，如下所示：

var img = $('#placeholder').get(0);
Holder.setResizeUpdate(img, false);

以上操作将暂停指定图像（必须是DOM对象）的渲染更新。

要重新启用更新，请运行以下操作

Holder.setResizeUpdate(img, true);

这将启用更新并立即渲染占位符。

背景占位符

Holder可以为具有holderjs类的元素渲染占位符作为背景图像，如下所示

#sample {background:url(?holder.js/200x200?theme=social) no-repeat}

<div id="sample" class="holderjs"></div>

CSS中的Holder URL前应有一个?。类似于图像占位符，您可以在data-background-src属性中指定Holder URL。

<div class="holderjs" data-background-src="?holder.js/300x200"></div>

重要：请确保为具有背景占位符的元素定义高度和/或宽度。目前不支持流体背景占位符。

运行时设置

Holder在运行时提供了一些选项，这些选项会影响图像生成过程。这些选项通过Holder.run调用传入。

domain：用于图像生成的域名。默认值：holder.js。
dataAttr：用于定义回退到本地src属性的HTML属性。默认值：data-src。
renderer：要使用的渲染器。可用选项：svg、canvas。默认值：svg。
images：用于查找img标签的CSS选择器。默认值：img。
objects：用于查找object占位符的CSS选择器。默认值：object。
bgnodes：用于查找具有背景占位符的元素的CSS选择器。默认值：body .holderjs。
stylenodes：用于查找要导入SVG占位符的样式的CSS选择器。默认值：head link.holderjs。
noFontFallback：使用自定义字体时不回退到canvas。
noBackgroundSize：不要为背景占位符设置background-size。

在加载时使用自定义设置

您可以通过在包含holder.js后立即使用您的自定义设置执行Holder.run来防止Holder运行其默认配置。但是，您需要再次执行Holder.run来渲染使用默认配置的任何占位符。

与lazyload.js一起使用

Holder与lazyload.js兼容，并且与流体和固定宽度图像一起工作。为了获得最佳效果，请运行.lazyload({skip_invisible:false})。

与React一起使用

当在React组件中使用Holder时，在状态更改后执行Holder.run以启用渲染。有关更多详细信息，请参阅此问题。

与Vue一起使用

您可以使用vue-holderjs在Vue 2+项目中使用Holder。

与Angular.js一起使用

您可以使用ng-holder或使用angular-2-holderjs（用于Angular 2项目）在Angular项目中使用Holder。

与Meteor一起使用

由于Meteor默认在文档顶部包含脚本，当调用Holder时，DOM可能尚未完全可用。因此，请将Holder相关代码放置在“DOM ready”事件监听器中。

与Webpack一起使用

如果您在Webpack配置中使用了ProvidePlugin，请确保按照以下方式配置它

plugins: [
  new webpack.ProvidePlugin({
    'Holder': 'holderjs',
    'holder': 'holderjs',
    'window.Holder': 'holderjs'
  })
]

浏览器支持

Chrome
Firefox 3+
Safari 4+
Internet Explorer 9+（对6-8的有限支持）
Opera 12+
Android（具有回退支持）

源代码

GitHub: https://github.com/imsky/holder
GitLab: https://gitlab.com/imsky/holder

许可

Holder在MIT许可证下提供。

致谢

Holder 是由 Ivan Malopinsky 执导的项目。

imsky / holder

维护者

详细信息