使用
快速开始
安装和引入方式请参考 安装 章节。
在 Vue 组件中使用
vue
<template>
<div class="demo">
<h2>按钮示例</h2>
<ea-button variant="primary">主要按钮</ea-button>
<ea-button variant="success">成功按钮</ea-button>
<ea-button variant="warning">警告按钮</ea-button>
<ea-button variant="danger">危险按钮</ea-button>
<h2>输入框示例</h2>
<ea-input v-model="inputValue" placeholder="请输入内容"></ea-input>
<h2>图标示例</h2>
<ea-button icon="fa-solid fa-heart">带图标的按钮</ea-button>
<ea-icon icon="fa-solid fa-star"></ea-icon>
</div>
</template>
<script setup>
import { ref } from "vue";
const inputValue = ref("");
</script>组件注册检测
与传统框架不同,自定义元素没有集中式的初始化阶段。这意味着在尝试与其属性或方法交互之前,您需要验证自定义元素是否已正确注册。
TIP
特别的,当与其属性或方法交互时,元素未进行相应更新。可以通过确认这点来排查问题。
js
// 等待组件注册完成
await customElements.whenDefined("ea-button");
const button = document.querySelector("ea-button");
// 现在可以安全地操作组件
button.disabled = true;HTML 安全边界
组件不内置运行期 HTML 清洗(不再依赖 DOMPurify)。模板由组件作者编写、视为可信;用户提供的属性值按纯文本插入,需要插入 HTML 时自行转义。
js
import { escapeHTML, html, setHTML } from "easy-component-ui";
// 动态值一律走 escapeHTML,属性上下文(含 class / name 等)同样适用
const label = '<img src=x onerror="alert(1)">';
setHTML(panel, html(`<span class="label">${escapeHTML(label)}</span>`));| API | 用途 |
|---|---|
escapeHTML() | 转义 & < > " ',所有动态值的默认选择 |
html() | 声明模板可信;不做清洗,模板里含内联事件等会告警 |
setHTML() | 唯一的 HTML 写入入口,负责把字符串写进元素或 ShadowRoot |
insertHTML() | 同上,用于在指定位置插入(afterbegin 等) |
TIP
确实需要渲染 HTML 的属性(如 ea-message 的 message)需显式开启对应开关,例如 dangerously-use-html-string;其余组件的 heading、label 等文本属性均按纯文本渲染,富文本请改用同名 slot。
注意事项
- 图标样式:如果组件使用了图标(如
ea-button的icon属性),必须引入icon-assets - ES Module:组件使用 ES Module 格式,需要通过
type="module"引入 - 自定义元素:所有组件标签以
ea-开头,如<ea-button>、<ea-input> - 主题样式:引入主包
easy-component-ui或按需引入单个组件时会自动注入语义变量层(setBaseStyles(themes/base));配色仍需引easy-component-ui/themes/source(深色再加themes/dark)。只引 core 自建组件时,需自行调setBaseStyles()或改用主题包的base.css,详见 主题切换