入门
让我们开始BootstrapVue之旅游,基于全球最流行的Bootstrap V4框架,构建移动优先的响应式门户,在Vue.js前端栈基础上。
全局版本规范:- Vue.js
v2.6
版, 推荐最低为v2.12.01
版。 - Bootstrap
4.3.1
,其推荐的版本是v4.4.1
版。 - Toasts发布的PortalVue
v2.1
,推荐最新是v2.1.7
版。 - jQuery 则 不是必须的(BootstrapVue不依赖Jquery)。
点此查看 BootstrapVue v2.12.0新增功能.
从 v2.0.0-rc.##
迁移,则请浏览
v2.0.0迁移指南
。
文档目录
本文档目录:
- 组件 Components - 组件和插件文档
- 指令 Directives - 指令和指令插件文档
- 图标 Icons - Icons图标手册 v2.2.0+
- 杂项 Miscellaneous - 扩展信息
- 体验 Playground - 在线体验例子
先决条件
使用 BootstrapVue前,建议你先熟悉Vue.JS的功能 和Bootstrap V4 Css框架,如果你还不熟悉它们,可以点下面的链接入手学习:
- Vue js使用指南
- Vue API
- Bootstrap v4.4 中文手册
- Vue loader scoped CSS, 如果使用scoped
styles组件 (单组件)
.vue
文件规范
文档资料
BootstrapVue的很多使用文档中,会用到 ml-2
、 py-1
,等Class类名,这些都是Bootstrap v4.4 通用样式类名,用于定义前端的填充、边距、定位等,可在实用 Class样式类表 浏览作为参考。
本文档许多例子是可以 实时运行作为测试的 ,以方便读者现场运行体验,提升学习成果(注意: <template>
节点由于使用了JavaScript ES6规范,所以部份示例无法在IE11中使用)。
BootstrapVue 还提供了一个 交互式的在线代码运行调试器,你可以在这里尝试各种组件,并将结果导出到JSFiddle、 CodePen、CodeSandbox等平台。
全局变量概要
为了满足跨浏览器支持和最大化符合HTML5规范以及w3c标准,Bootstrap v4 CSS使用了一系列重要的全局样式和设置,使用时需要注意,下面各小节将详细讲述。
HTML5 doctype规范
Bootstrap 是基于 HTML5
规范的,u 脱离 它则不能获得完整有效的样式呈与功能呈现,并带来不可预期的困扰,下面是一个标准的HTML5网页头部规范(译者将原英文头部lang标签改为中文,以符合中文读者):
响应式meta标记
Bootstrap 强调移动优先策略,所以需要针对设备进行meta头部定义,并支持CSS媒体查询,为了保证所有设备都能正确渲染、满足移动触屏幕的缩放要求,请在网页头部 <head>
区增加相关定义,如下所示:
CSS box-sizing属性
为了支持在CSS中能调整大小,我们将box-sizing
中的 content-box
属性替换为 border-box
,这样可以确保填充padding
不会影响到元素的最终宽度计算,但会导致某些第三方软件(如 Google Maps 、 Google Custom Search
Engine)出现问题。
少数情况下你需要覆盖它,请使用下面的CSS指导操作:
使用上面的代码版断,嵌套元素,(包括通过 ::before
、 ::after
—
都能接受继承,从而指定box-sizing
元素在 .selector-for-some-widget
类上的表现。
你可以通过css-tricks网站查看box model and sizing属性知识。
样式重置
为改善和统一在各个浏览中的表现, Bootstrap v4.4 使用 Reboot样式重置(即根元素重置) 来纠正各个浏览器和设备间的差异,同时为常见的HTML 元素提供更多的私有扩展和重置规范。
基于模块化
你可以使用Webpack、 Parcel 、 rollup.js等方法引入到项目中,通过yarn
或者 npm
来获取安装Vue.js、 BootstrapVue 和 Bootstrap v4:
然后在你的应用程序入口点注BootstrapVue:
然后引入 Bootstrap 和BootstrapVue的css
文件:
或者引入 Bootstrap 和 BootstrapVue的 scss
文件用于驱动SCSS混合:
最后在程序的入口文件引入 custom.scss
:
在包含之前,请务必使用 @import
定义你的变量值,同时包含 Bootstrap SCSS
(bootstrap.scss
)、BootstrapVue SCSS (bootstrap-vue.scss
) 以确保正确的变量。
将所有的SCSS @import
在一个SCSS 文件中,然后将该单文件引入(这是scss的基本方法,默认情况下,单个SCSSS导入项目,不会在文件之间共享变量和函数(从而避免变量与函数冲突)。
当从scss文件导入时,Webpack和Parcel支持在scss模块前面加上波浪号(〜):
有关如何配置装载以及如何解决模块的更多详细信息,敬请查阅下方模块捆绑文档:
- Webpack configuration to load CSS files (官方指南)
- Webpack Loader for SASS/SCSS files (官方指南)
- Parcel CSS (官方指南)
- Parcel SCSS (官方指南)
有关BoostrapVue主题引导程序的信息,请查看主题参考 部分。
在 Vue中灵活引用
BootstrapVue 和 PortalVue 需要访问 Vue
全局类实现引用 (通过 import Vue from 'vue'
来实现)。
如果您使用的是特定版本的Vue(例如,仅运行时与VS编译器运行),则需要在捆绑程序配置中为“ vue”设置别名,以确保您的项目,BootstrapVue和PortalVue都在使用 相同版本的Vue。 如果看到"$attr and $listeners is readonly"
、 "Multiple instances of Vue detected"
等错误时,您则需要设置一个别名。
例子: Vue 在 webpack.config.js中的别名处置
提示: 如果您的项目具有多个webpack配置文件 (例如 webpack.config.js
、 webpack.renderer.config.js
、webpack.vendor.config.js
、 webpack.server.config.js
、 webpack.client.config.js
等等),则需要在这些配置中中设置适当的别名。
点击浏览 Vue.js 中关于 webpack、rollup.js、Parcel等配置的详细文档。
模块捆绑
使用模块捆绑时,可以选择仅导入特定的组件(插件)、指令,注意这仅迁于JavaScript代码,不适用于CSS/SCSS.
提示: 仅当 webpack 4 在 production
模式并助启用了最小化设置,才有效。
以嵌套组件和指令方式作用于vue插件
Y您可以通过从导入将组件组和指令作为Vue插件导入 bootstrap-vue
:
// This imports all the layout components such as <b-container>, <b-row>, <b-col>:
各个组件和指令
如果您只想引入一个特定的组件或一组组件,则可以通过直接导入这些组件来实现。
要挑选一个组件/指令,请先将其导入使用文件中:
// Place all imports from 'bootstrap-vue' in a single import
// statement for optimal bundle sizes
import { BModal, VBModal } from 'bootstrap-vue'
然后将其添加到您的组件定义中:
Vue.component('my-component', {
components: {
'b-modal': BModal
},
directives: {
// Note that Vue automatically prefixes directive names with `v-`
'b-modal': VBModal
}
// ...
})
或在全局注册:
Vue.component('b-modal', BModal)
// Note that Vue automatically prefixes directive names with `v-`
Vue.directive('b-modal', VBModal)
Vue在这里允许使用各种组件和指令名称语法,因此可以随意使用 kebab-casing(如图所示),camelCasing,PascalCasing 和/或 object 属性速记(仅限组件)。
将BootstrapVue源代码用于较小的捆绑软件
使用模块捆绑程序时,它们通常将默认使用 esm/
模块化构建,该构建已由 Babel 预编译为 supported browsers (支持的浏览器) 。
您可以通过别名化'bootstrap-vue'
以使用 BootstrapVue 源文件来覆盖 esm/
build 的使用,并在模块捆绑程序配置中将 node_modules/bootstrap-vue/src/*
列入白名单以在构建过程中进行编译。 允许您为目标浏览器/环境转换BootstrapVue,并可能减小捆绑包的大小(并且仅包含babel helper utils一次),但会花费更长的构建时间。
用于 Babel 移植的示例 webpack.config.js:
module.exports = {
resolve: {
alias: {
// Alias for using source of BootstrapVue
'bootstrap-vue$': 'bootstrap-vue/src/index.js'
}
},
module: {
rules: [
{
test: /\.js$/,
// Exclude transpiling `node_modules`, except `bootstrap-vue/src`
exclude: /node_modules\/(?!bootstrap-vue\/src\/)/,
use: {
loader: 'babel-loader',
options: {
presets: ['env']
}
}
}
]
}
}
您可能需要安装 babel-core
, babel-loader
,和 babel-preset-env
:
# If using npm
npm install babel-core babel-loader babel-preset-env --save-dev
# If using yarn
yarn add babel-core babel-loader babel-preset-env --dev
有关更多详细信息,请参见:
Nuxt.js模块
BootstrapVue 提供了一个 Nuxt.js 模块,可以轻松地将 BootstrapVue(或BootstrapVue的一部分)导入到Nuxt.js应用程序中。
Nuxt.js入门
建议使用 Nuxt.js 2.11.0
版(或更高版本)
安装依赖:
# With npm
npm install bootstrap-vue
# With yarn
yarn add bootstrap-vue
将 bootstrap-vue/nuxt
添加到 nuxt.config.js
文件的 modules 部分。
这将包括 bootstrap.css
和 bootstrap-vue.css
默认的预编译CSS。
module.exports = {
modules: ['bootstrap-vue/nuxt']
}
请注意,这 不会 安装 Icons 组件。要查看如何通过 Nuxt.js 模块包括图标,请参阅下面的 Icons section 部分。
使用自定义 Bootstrap SCSS
如果使用自定义的 Bootstrap SCSS,则可以通过将以下选项设置为 false
来禁用自动包含 Bootstrap 和 BootstrapVue 预编译的CSS文件。
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
bootstrapCSS: false, // Or `css: false`
bootstrapVueCSS: false // Or `bvCSS: false`
}
}
BootstrapVue 的自定义 SCSS 依赖于 Bootstrap SCSS 变量和 mixins,以及您可能设置的任何变量覆盖。您可以在项目的自定义 SCSS 文件中包括 Bootstrap 和 BootstrapVue SCSS:
// custom.scss
// Custom Bootstrap variable overrides go first
$grid-breakpoints: (
xs: 0,
sm: 480px,
md: 640px,
lg: 992px,
xl: 1300px
);
$enable-rounded: false;
// Then include the following
@import 'bootstrap/scss/bootstrap.scss';
@import 'bootstrap-vue/src/index.scss';
// And define any of your custom or additional CSS/SCSS here,
// or via an @import
在应用程序的主入口中,包括 单个 自定义SCSS文件(使用 sass-loader
时):
// app.js
import 'custom.scss'
使用 Nuxt.js 的 transformAssetUrls
BootstrapVue Nuxt 插件模块将为您自动添加特定于 BootstrapVue 的 transformAssetUrls
图像 src
属性配置。 image prop configuration for you.
用 Nuxt.js 握手
如果由于只使用可用的 BootstrapVue 插件的一部分而希望减小生产包的大小,则可以配置要全局安装在 Nuxt.js 项目中的 BootstrapVue componentPlugins
或 directivePlugins
的列表。JavaScript 代码,而不是 CSS / SCSS。
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
componentPlugins: [
'LayoutPlugin',
'FormPlugin',
'FormCheckboxPlugin',
'FormInputPlugin',
'FormRadioPlugin',
'ToastPlugin',
'ModalPlugin'
],
directivePlugins: ['VBPopoverPlugin', 'VBTooltipPlugin', 'VBScrollspyPlugin']
}
}
在 componentPlugins
选项中提供了两个附加的帮助程序插件,用于提供 $bvModal
和 $bvToast
注入(如果您未使用 ModalPlugin
或 ToastPlugin
插件):
BVModalPlugin
- 提供注入$bvModal
以生成 message boxes【消息框】。BVToastPlugin
- 提供注入$bvToast
以生成 on demand toasts【按需吐司】。
您还可以通过配置要全局安装在 Nuxt.js 项目中的 BootstrapVue 组件或指令的列表,有选择地导入单个 components
【组件】和/或 directives
【指令】。
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
components: ['BContainer', 'BRow', 'BCol', 'BFormInput', 'BButton', 'BTable', 'BModal'],
directives: ['VBModal', 'VBPopover', 'VBTooltip', 'VBScrollspy']
}
}
随意将插件导入与单个组件和指令导入混合和匹配。
请参阅每个 component【组件】和 directive【指令】文档底部的参考部分,以获取有关可用插件名称(以及每个插件中包含哪些组件和指令)以及组件和/或指令导入名称的详细信息。
请注意,导入单个组件时,任何组件别名都将 不可用。
注意:只有当您的Nuxt.js应用程序处于 production
【生产】模式时,最佳摇晃树才能发挥作用。在 not in production
非生产模式(即 dev
【开发】模式)下,您可能会注意到捆绑包尺寸更大。
如果要将单个 BootstrapVue 组件导入到 特定 页面 和/或 Nuxt 应用程序的组件中,则可能要绕过 Nuxt.js 模块,而是遵循上述 module bundlers 【模块捆绑器】和 Tree shaking with module bundlers【用模块捆绑器一起进行的握手】。
另外,您可能只想在 Nuxt.js 模块配置中导入一些插件(例如 LayoutPlugin
),然后在需要的页面中导入其他组件或插件。
Icons 图标
使用 Nuxt.js 模块时,icons 插件 不会 自动安装。您必须显式启用 IconsPlugin
或指定要导入的图标组件。
所有 icons 图标:
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
icons: true // Install the IconsPlugin (in addition to BootStrapVue plugin
}
}
具体 icons 图标:
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
// Add the desired icon components to the `components` array
components: ['BIcon', 'BIconAlertFill', 'BIconCalendar', 'BIconGears']
}
}
Icons 图标插件:
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
// Add the icon plugin to the `componentsPlugins` array
componentPlugins: ['IconsPlugin']
}
}
通过 Nuxt.js 传递自定义 BootstrapVue 配置
如果您需要传递自定义的 BootstrapVue 配置 ,可以通过在 nuxt.config.js
中设置 config
属性来实现:
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
config: {
// Custom config options here
}
}
}
对 Nuxt.js 使用 BootstrapVue 的预编译版本
Nuxt.js 模块使用 BootstrapVue 的预编译版本来加快开发构建,并使用BootstrapVue的源( src/
)来获得更高质量和更小批量生产。
您可以使用 usePretranspiled
选项覆盖此选项。设置为 true
总是使用预编译版本,而将其设置为 false
则始终使用 src/
默认情况下,usePretranspiled
仅在开发模式下启用。默认值是性能最佳的。
Vue CLI 3
与 V2 不同,Vue CLI 3不使用模板。
在目录 my-project
中创建一个新项目:
npx @vue/cli create my-project
输入 my-project
目录并安装 bootstrap-vue
:
npm install bootstrap-vue
在后台,Vue CLI 使用 webpack,因此我们可以按照 webpack 的说明注册 BootstrapVue 插件。
import Vue from 'vue'
import { BootstrapVue, BootstrapVueIcons } from 'bootstrap-vue'
import 'bootstrap/dist/css/bootstrap.css'
import 'bootstrap-vue/dist/bootstrap-vue.css'
Vue.use(BootstrapVue)
Vue.use(BootstrapVueIcons)
有关在各种 BootstrapVue 组件上将项目相对路径用于image src 属性的 Vue CLI 3的其他配置,请参阅 Image Src Resolving 参考页面的 Vue CLI 3部分。
Vue CLI 3 插件
或者,您可以使用 Bootstrap-Vue Vue CLI 3 插件 来帮助您配置应用程序。
vue create my-app
cd my-app
vue add bootstrap-vue
这将创建一个具有基本 BootstrapVue 设置的新应用,以启动您的项目。
将来,该插件将提供更多高级配置和模板的选项。
对于图标支持,您可能需要编辑生成的配置文件。
浏览器
如果未使用模块捆绑程序或编译过程,则可以在 HTML <head>
部分中添加 Bootstrap 和 BootstrapVue CSS URL,然后添加所需的 JavaScript 文件。
在支持较旧的浏览器时(请参见下面的 Browser Support【浏览器支持】),在加载 Vue 和 BootstrapVue JavaScript 文件之前,您需要包括一个 polyfill 以处理现代 JavaScript 功能。
<!-- Add this to <head> -->
<!-- Load required Bootstrap and BootstrapVue CSS -->
<link type="text/css" rel="stylesheet" href="//unpkg.com/bootstrap/dist/css/bootstrap.min.css" />
<link type="text/css" rel="stylesheet" href="//unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.min.css" />
<!-- Load polyfills to support older browsers -->
<script src="//polyfill.io/v3/polyfill.min.js?features=es2015%2CIntersectionObserver" crossorigin="anonymous"></script>
<!-- Load Vue followed by BootstrapVue -->
<script src="//unpkg.com/vue@latest/dist/vue.min.js"></script>
<script src="//unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.min.js"></script>
<!-- Load the following for BootstrapVueIcons support -->
<script src="//unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue-icons.min.js"></script>
构建变量
为您的构建环境/打包器选择最佳变体有助于减小捆绑包的大小。如果捆绑包支持 esm 模块,它将自动优先于 commonjs 。
变量 | 环境 | 握手 | 包路径 |
---|---|---|---|
ESM module | webpack 2+ / rollup.js | Yes | esm/index.js |
ESM bundle | webpack 2+ / rollup.js | Yes | dist/bootstrap-vue.esm.js |
commonjs2 | webpack 1 / ... | No | dist/bootstrap-vue.common.js or dist/bootstrap-vue.common.min.js |
UMD | Browser | No | dist/bootstrap-vue.js or dist/bootstrap-vue.min.js |
请注意,UMD(浏览器)变体不包含BootstrapVue icons 图标支持,上面列出的所有其他变体 都包含 BootstrapVueIcons
(IconsPlugin
)插件(请注意,Icons usage【图标插件】 不会 自动安装,必须通过 Vue.use()
进行显式安装。图标使用情况部分,以了解更多详细信息。
仅图标模块:
变量 | 环境 | 握手 | 包路径 |
---|---|---|---|
ESM bundle | webpack 2+ / rollup.js | Yes | dist/bootstrap-vue-icons.esm.js |
commonjs2 | webpack 1 / ... | No | dist/bootstrap-vue-icons.common.js or dist/bootstrap-vue-icons.common.min.js |
UMD | Browser | No | dist/bootstrap-vue-icons.js or dist/bootstrap-vue-icons.min.js |
ESM
模块的构建和 ESM
捆绑包(单个文件)是 tree-shakeable【可握手】的,但是 与 ESM
捆绑包相比,使用 ESM
模块时,最终捆绑包的尺寸会更小。
上面列出的所有构建变量均已针对 BootstrapVue 支持的 浏览器 进行了预编译,但是,如果仅针对现代浏览器,则可能要从 src/index.js
导入 BootstrapVue
(通过将 bootstrap-vue
别名为 bootstrap-vue/src/index.js
)并将 bootstrap-vue/src
列入白名单以通过您自己的项目进行移植,这有可能减小最终项目包的大小。有关更多详细信息,请参见上面的 将BootstrapVue源代码用于较小的捆绑软件 。
依存关系
BootstrapVue 依赖于 Popper.js
(用于 Tooltip ,Popover 和 Dropdown 定位),PortalVue
(用于吐司)和 vue-functional-data-merge
(由我们的功能组件使用)这三个依赖项都包含在 BootstrapVue UMD
捆绑包中,而 仅 UMD(浏览器)图标包包含 vue-functional-data-merge
。
已使用 Bootstrap 迁移项目
如果您已经在使用 Bootstrap v4,则可能需要对项目进行一些调整:
- 从页面脚本或构建管道中删除
bootstrap.js
文件 file from your page scripts or build pipeline - 如果 Bootstrap 是唯一依赖
jQuery
的东西,则可以安全地删除它-BootstrapVue 不依赖jQuery
- 将您的本机 Bootstrap HTML 标记转换为简化的 BootstrapVue 自定义组件标记
- 首先仅转换需要 Bootstrap javascript 的交互式控件。
浏览器支持
CSS
BootstrapVue与Bootstrap v4.4 CSS / SCSS一起使用。 有关Bootstrap v4当前支持的浏览器的更多信息,请参见 Browsers and devices【浏览器和设备】。
JS
BootstrapVue 用 Vue.js编写!因此,支持哪种浏览器取决于您的项目和捆绑软件。
BootstrapVue使用以下功能和API:
- ES6 (即
Array.from()
,Array.isArray()
,Object.assign()
,Object.is()
, 等) Promise
MutationObserver
IntersectionObserver
(可选的)
如果要支持较旧的 IE ,Android 和 iOS 设备 Web 浏览器,则可能要使用 core-js 和 intersection-observer【交集观察器】:
npm install core-js regenerator-runtime intersection-observer
然后将 polyfills 导入应用主入口:
import 'core-js/stable'
import 'regenerator-runtime/runtime'
import 'intersection-observer' // Optional
import Vue from 'vue'
import BootstrapVue from 'bootstrap-vue'
如果使用已弃用的 @babel/polyfill:
npm install @babel/polyfill intersection-observer
然后将 polyfills 导入应用主入口:
import '@babel/polyfill'
import 'intersection-observer' // Optional
import Vue from 'vue'
import BootstrapVue from 'bootstrap-vue'
或者,使用 Polyfill.io 通过 HTML <head>
部分中的 <script>
标记动态提供浏览器特定的polyfill。 有关示例,请参见上面的 Browser【浏览器 】部分。
工具支持
BootstrapVue 提供了其他帮助程序文件,可在流行的 IDE 编辑器中自动完成。
VS Code + Vetur
如果您使用 VS Code 作为文本编辑器,则BootstrapVue具有Intellisense自动补全功能,可通过 dist/vetur-tags.json
和 dist/vetur-attributes.json
文件使用组件属性和指令。
JetBrains WebStorm (兼容)
对于 WebStorm 编辑器(或与Web类型兼容),BootstrapVue提供文件 dist/web-types.json
用于组件属性和指令自动完成。