暄风吹斋响苍玉,竹石相看便有情。提胡卢来沽美酒,终日撩人不住声。

SweetAlert弹窗插件中文API(一):快速入门

说明


官方网址:https://sweetalert.js.org/guides/

插件版本:2.0.1

文档汉化:Joey Yan

汉化说明:本人英语能力有限,如有不正确的地方欢迎在下方评论留言,或直接在线与我联系。

安装


NPM/Yarn

官网推荐的安装方法,使用命令行工具npmYarn来安装SweetAlert

1
npm install sweetalert --save

然后,只需使用以下代码即可将其导入到您的应用程序:

1
import swal from 'sweetalert';

CDN

您还可以在unpkg和jsDelivr网站上上找到SweetAlert的CDN服务,直接引用并使用全局变量swal

1
<script src="https://unpkg.com/sweetalert/dist/sweetalert.min.js"></script>

开始使用


显示一个基本弹窗

将文件导入应用程序后,可以调用swal函数(请确保在DOM加载后再调用它!)来生成一个弹窗,参数为弹窗显示的内容,首先让我们从Hello world!开始

1
swal("Hello world!");

如果传递两个参数,那么第一个参数将是弹窗的标题,第二个参数是弹窗显示的文本。

1
swal('这是一个标题!', '...这是弹窗显示的文本!');

添加第三个参数,您就可以在弹窗中添加一个动态图标!一共有4个预定义好的参数:"warning""error""success""info"。分别表示“警告”、“错误”、“成功”和“信息”。

1
swal('干得漂亮!', '你点击了这个按钮!','success');

选项配置

除了如上一步中快速生成一个弹窗外,也可以使用一个JSON对象作为唯一参数重写弹窗参数的方式来生成一个弹窗,如上一个示例中,如果使用参数重写方法,则代码为:

1
2
3
4
5
swal({
title: "干得漂亮!",
text: "你点击了这个按钮!",
icon: "success",
});

使用这种方式生成弹窗,我们可以指定更多的选项来自定义弹窗。例如,我们可以将弹窗的确认按钮的文本改为"没错!"

1
2
3
4
5
6
swal({
title: "干得漂亮!",
text: "你点击了这个按钮!",
icon: "success",
button: "没错!",
});

你也可以将基本写法与选项配置结合着使用,这样做可以为您节省一些写代码的时间:

1
2
3
swal("干得漂亮!", "你点击了这个按钮!", "success", {
button: "没错!",
});

获取交互状态

SweetAlert使用promises对象来跟踪用户如何与弹窗交互。如果用户单击确认按钮,则promise将返回true。如果弹窗被关闭(通过单击它外部),则promise将返回null

1
2
3
4
swal("请单击按钮或弹窗的外部来关闭弹窗。")
.then((value) => {
swal(`返回的值为: ${value}`);
});

如果您想在执行关键操作之前警告用户,获取交互状态就可以派上用场。通过设置更多选项,我们还可以让弹窗变得更完善。

  • 通过将icon参数设置为预定义的"warning",以显示一个漂亮的警告图标。
  • 通过将buttons(复数)参数设置为true,SweetAlert除了显示默认的确认按钮之外,还将显示一个取消按钮。
  • 通过将dangerMode参数设置为true,焦点将会自动设置在取消按钮而不是确认按钮上,并且确认按钮将会从默认的蓝色变为红色,以强调这是一个关键的操作。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
swal({
title: "操作确认",
text: "删除后,您将无法恢复此虚拟文件!",
icon: "warning",
buttons: true,
dangerMode: true,
})
.then((willDelete) => {
if (willDelete) {
swal("噗!您的虚拟文件已被删除!", {
icon: "success",
});
} else {
swal("你的虚拟文件是安全的!");
}
});

高级用法


自定义按钮

在基础用法中,我们已经学到了如何将确认按钮的文本设置为没错!。如果还想显示自定义的取消按钮,我们可以将buttons参数的值设置为字符串数组,数组中第一个值是取消按钮的文本,第二个值是确认按钮的文本:

1
2
3
swal("你确定要这么做吗?", {
buttons: ["哦不!", "没错!"],
});

如果您只想修改其中一个按钮的默认文本,那么不需要修改的那个按钮你可以赋值为true而不是字符串:

1
2
3
swal("你确定要这么做吗?", {
buttons: ["哦不!", true],
});

那么如果您需要的不仅仅是取消和确认按钮呢?别担心,SweetAlert依旧能够满意你的要求!

通过为按钮指定参数,您可以根据需要设置一个按钮,并指定它们在单击时返回的值!

在下面的示例中,我们设置了3个按钮:

  • cancel参数,默认情况下返回值为null并将其文本设置为"快跑!"
  • catch参数,它将生成一个自定义按钮,文本内容为"扔神奇宝贝!",返回值为"catch"
  • defeat参数。我们将其设定为true,让SweetAlert为按钮设置一些默认配置。在这种情况下,它会将文本内容设置为"Defeat"(大写),返回值设置为"defeat"。如果我们将取消按钮设置为true,它仍将默认返回null
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
swal("前方出现了一只野生的宠物小精灵,你想要怎么做?", {
buttons: {
cancel: "逃跑!",
catch: {
text: "扔神奇宝贝球!",
value: "catch",
},
defeat: true,
},
})
.then((value) => {
switch (value) {
case "defeat":
swal("宠物小精灵被你打败了,你获得500经验值!");
break;
case "catch":
swal("恭喜", "你抓到这只宠物小精灵了!", "success");
break;
default:
swal("你安全了!");
}
});

您可以在文档中查看所有的可用按钮选项。

AJAX请求

由于SweetAlert是基于promise对象的,所以SweetAlert可以使用基于promise的AJAX请求函数。下面是一个使用fetch在iTunes API上搜索艺术家的示例。请注意,我们使用了"input"控件,以便在用户单击确认按钮时显示输入的字段内容并获取它的值:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
swal({
text: '请输入想要搜索的电影名称,如:“Fast & Furious”',
content: "input",
button: {
text: "搜索!",
closeModal: false,
},
})
.then(name => {
if (!name) throw null;
return fetch(`https://itunes.apple.com/search?term=${name}&entity=movie`);
})
.then(results => {
return results.json();
})
.then(json => {
const movie = json.results[0];

if (!movie) {
return swal("未找到相关的内容!");
}

const name = movie.trackName;
const imageURL = movie.artworkUrl100;

swal({
title: "最佳匹配:",
text: name,
icon: imageURL,
});
})
.catch(err => {
if (err) {
swal("失败", "AJAX请求失败!", "error");
} else {
swal.stopLoading();
swal.close();
}
});

使用DOM节点作为弹窗内容

有时候,你可能会遇到这样一个场景:使用SweetAlert提供的开箱即用功能非常便利,但是有一些自定义的用户界面可能不仅仅需要样式按钮和文本。为此,SweetAlert准备了content参数。

在上一个示例中,我们看到了如何将content参数设置为"input"以在我们的弹窗中生成一个<input />元素,当点击确认按钮时,其默认的返回值trye将被替换为<input />元素所输入的内容。"input"是为方便起见而存在的预定义选项,您可以将content参数的值设置为任何的DOM节点!

让我们来看看,如何重新创建以下弹窗的功能……

1
2
3
4
5
6
swal("请在下面的文本框中随意输入一些内容:", {
content: "input",
})
.then((value) => {
swal(`您输入的内容为:${value}`);
});

…使用自定义DOM节点!

我们将在这里使用React UI库,他可以帮助我们了解如何创建更复杂的SweetAlert,您也可以使用任何其他你熟悉或所需的库,只要您可以从中提取DOM节点!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
import React, { Component } from 'react';
import ReactDOM from 'react-dom';

const DEFAULT_INPUT_TEXT = "";

class MyInput extends Component {
constructor(props) {
super(props);

this.state = {
text: DEFAULT_INPUT_TEXT,
};
}

changeText(e) {
let text = e.target.value;

this.setState({
text,
});

/*
* This will update the value that the confirm
* button resolves to:
*/
swal.setActionValue(text);
}

render() {
return (
<input
value={this.state.text}
onChange={this.changeText.bind(this)}
/>
)
}
}

// We want to retrieve MyInput as a pure DOM node:
let wrapper = document.createElement('div');
ReactDOM.render(<MyInput />, wrapper);
let el = wrapper.firstChild;

swal({
text: "Write something here:",
content: el,
buttons: {
confirm: {
/*
* We need to initialize the value of the button to
* an empty string instead of "true":
*/
value: DEFAULT_INPUT_TEXT,
},
},
})
.then((value) => {
swal(`You typed: ${value}`);
});

触一开始看起来或许会觉得很复杂,但实际上非常简单。我们所做的只是创建一个<input />标签作为React组件。然后,我们提取其DOM节点并将其做为swal函数中content参数的值,以将其呈现为无样式元素。

其唯一的区别在于SweetAlert的代码是swal.setActionValue()和最后的swal()调用。其余的都只是基本的React和JavaScript。

使用这种技术,我们可以创建具有更多交互式UI的模态,例如来自Facebook的这种模式。

较1.X版本的升级

SweetAlert 2.0引入了一些重大的变化,以使库更易于使用并且更加的灵活。

最重要的变化是promises不再推荐使用回调函数,并且您不再需要导入任何外部CSS文件(因为样式现在全部捆绑在了.js文件中)。

以下是一些其他已被弃用的方法及其替代方法:

  • 当使用单个字符串参数(例如:swal("Hello world!"))时,在2.0版本中该参数设置的是弹窗的文本,而在1.0中,该参数设置的是其标题
  • typeimageUrl两个参数在2.0版本中已替换为单个icon参数。如果您使用的是基础弹窗(swal("Hi", "Hello world", "warning")),则无需进行任何更改。
  • customClass参数在2.0版本中更名为className
  • 弃用imageSize参数,在2.0版本中,您需要在CSS中指定相应的尺寸限制。如果您有特殊用例,则可以为组件提供自定义的CLASS。
  • 弃用showCancelButtonshowConfirmButton参数,在2.0版本中,您可以通过设置buttons: true来表示显示默认配置的按钮,或buttons: false表示隐藏所有按钮。默认情况下,仅显示确认按钮。
  • 弃用confirmButtonTextcancelButtonText参数。在2.0版本中,您可以设置buttons: "foo"将确认按钮上的文本设置为foot,或buttons: ["foo", "bar"]将取消按钮上的文本设置为foo,将确认按钮上的文本设置为bar
  • 弃用confirmButtonColor参数。在2.0版本中,您应该通过CSS指定所有样式的更改。作为预设的简写,您可以设置dangerMode:true以将确认按钮变为红色。或者,您可以在buttons参数中为每一个按钮指定一个CLASS。
  • 弃用closeOnConfirmcloseOnCancel。在2.0版本中,您可以在buttons参数中为每个按钮设置closeModal参数。
  • 弃用showLoaderOnConfirm参数。在2.0版本中,当按钮的closeModal参数设置为false时,您的按钮将自动显示loding动画。
  • 弃用animation参数。在2.0版本中,所有样式更改都可以通过CSS和自定义弹窗CLASS来实现。
  • type: "input", inputType, inputValueinputPlaceholder参数在2.0版本中都已被content对象替代。您可以通过指定content: "input"以获取默认选项,也可以使用content对象进一步自定义内容。
  • 在2.0中不再使用HTML。而是使用content对象。
  • 为消除歧义,更清晰描述参数的功能,allowEscapeKey参数在2.0版本中更名为closeOnEsc
  • 为消除歧义,更清晰描述参数的功能,allowClickOutside参数在2.0版本中更名为closeOnClickOutside
-------------本文结束感谢您的阅读-------------
坚持原创技术及精品文章分享,您的支持将鼓励我继续创作!
0%