# @greypan/web-ui
> 基于 Lit 的 Web Components，支持 React、Vue 和原生 HTML
[English](./README.md) | 简体中文
## 演示
[查看组件在 vue 中使用](https://pan-z2l0ahvi.github.io/mono/vue-web-ui-demo/)
[查看组件在 react 中使用](https://pan-z2l0ahvi.github.io/mono/react-web-ui-demo/)
## 安装
```bash
npm install @greypan/web-ui
```
需要 `lit` 作为依赖。
## 快速开始
```js
import '@greypan/web-ui'
// import '@greypan/web-ui/components/button'
```
```html
点击我
```
## 框架集成
### 跨框架 API 约定
`web-ui-*` 元素暴露三面 API，**DOM / JavaScript API 是事实来源**：Property 使用 camelCase，Attribute 使用
kebab-case，Event 使用 kebab-case。
| 表面 | 命名 | 示例 |
| --------- | ---------- | --------------------------------------------- |
| Property | camelCase | `open`、`sidebarCollapsed`、`noScrollLock` |
| Attribute | kebab-case | `open`、`sidebar-collapsed`、`no-scroll-lock` |
| Event | kebab-case | `open-change`、`sidebar-collapsed-change` |
- **布尔 Attribute** 遵循原生 HTML 存在语义：不存在 → `false`，存在 → `true`。框架绑定写入的
`disabled="false"` 是字符串 `"false"`，会被视为 true——**动态布尔必须绑定 Property**（camelCase），
才能把 `false` 写成真实 property。
- **Vue**：动态绑定必须走 **Property**，使用 camelCase 属性名（`:sidebarCollapsed="x"`、`:open="x"`）。
kebab-case 绑定（`:sidebar-collapsed="x"`）会被写成字符串 attribute，无法表达 `false`，请使用 camelCase
property。`.prop` 修饰符只在 camelCase 属性名下有效（`:sidebarCollapsed.prop="x"`）。String/Number 值可
保留 kebab-case attribute（`:max-height="120"`）。带值控件（`web-ui-input`、`web-ui-select`、
`web-ui-autocomplete` 等）支持 `v-model`，编译为元素的 `value` property + `input` 事件。
- **React**：React 19 对 custom element 的 props 直接写 DOM property，因此使用 camelCase props
（`open={open}`、`noScrollLock`、`value={value}`）。**不要把复杂数据（对象、数组）放进 attribute 字符串**，
一律绑定为 property。kebab-case JSX prop 在 custom element 上会写成 attribute。
### React
需要 `@types/react >= 19` 作为可选 peer 依赖。
```ts
// vite.config.ts
import unpluginWebComponents from '@greypan/unplugin-web-components/vite'
export default {
plugins: [unpluginWebComponents({ tagPrefix: 'web-ui', packageName: '@greypan/web-ui', sideEffects: true })]
}
// env.d.ts
import '@greypan/web-ui/types/react'
```
```tsx
import '@greypan/web-ui'
function App() {
return (
<>
alert('点击')}>
按钮
console.log(e.currentTarget.value)} />
)
}
```
#### React 自定义元素事件与布尔属性
React 19 按 JSX 键名中的 `on` 后缀原样注册 Custom Element 事件。事件名大小写敏感：`open-change`
必须绑定为 `onopen-change`，不能写成 `onOpenChange`。标准 `input`、`change`、`focus`、`blur`
事件使用 React 惯用的 `onInput`、`onChange`、`onFocus`、`onBlur` handler——其 `currentTarget`
类型为组件实例，value/checked 读取无需 cast；`target` 遵循 React SyntheticEvent 语义（`EventTarget`），
不承诺为组件实例。kebab-case 自定义事件携带精确类型的 `CustomEvent` detail。
布尔属性遵循原生 HTML 语义：属性缺失为 `false`，属性存在为 `true`。
```tsx
setOpen(event.detail.open)}
/>
setValue(event.currentTarget.value)} />
```
当组件会把子元素移入自身的 Portal Shadow DOM（例如 `web-ui-dropdown` 的菜单项）时，React 根节点的
合成 `onClick` 无法收到该子元素的事件。需要通过 `ref` 直接绑定原生事件：
```tsx
const itemRef = useRef(null)
useEffect(() => {
const item = itemRef.current
if (!item) return
const close = () => setOpen(false)
item.addEventListener('click', close)
return () => item.removeEventListener('click', close)
}, [])
粘贴并关闭
```
### Vue
需要 `vue >= 3.5` 作为可选 peer 依赖。
```ts
// vite.config.ts
import vue from '@vitejs/plugin-vue'
import unpluginWebComponents from '@greypan/unplugin-web-components/vite'
export default {
plugins: [
vue({
template: { compilerOptions: { isCustomElement: tag => tag.startsWith('web-ui-') } }
}),
unpluginWebComponents({ tagPrefix: 'web-ui', packageName: '@greypan/web-ui', sideEffects: true })
]
}
// env.d.ts
import '@greypan/web-ui/types/vue'
```
```vue
按钮
```
Boolean 属性必须用 **camelCase 属性名**绑定，而不是 kebab-case attribute。Vue 会把 attribute 绑定写成字符串，
而布尔 attribute 遵循「存在即 true」的语义——所以 `:sidebar-collapsed="false"` 会写出字符串 `"false"`，被当作 true。
改用 camelCase 属性名（`:sidebarCollapsed="false"`，或 `.prop` 修饰符）会让 Vue 直接写 DOM property：
```vue
```
Vue 事件类型零 cast：带值组件上的 `@input`/`@change` 解析到组件 emit，`$event.target` 即为组件实例，
`value`/`checked` 直接读取；kebab-case 事件（如 `open-change`）的 `$event.detail` 保持 `CustomEvent` 载荷类型。
命名 handler 用 `WebUiEvent` 标注；当变量或泛型表示事件名时，使用
`WebUiEventName`，它只接受该组件 `$events` 的 string key。未声明为 emit 的原生事件
（`@click`/`@focus` 等）在任何 `web-ui-*` 元素上仍可绑定。
### 属性与事件边界
`web-ui-*` 元素是公开 DOM 边界。`id`、`class`、`style`、全局 HTML 属性和 `data-*` 保留在 Custom Element 宿主上，
不会复制到 Shadow DOM。只有组件文档明确声明语义映射时，原生元素属性才会传递。例如 `web-ui-button` 会把 `type`
映射到内部按钮，且仅接受 `button`、`submit`、`reset`；非法值会回退为 `button`。
ARIA 属性同样必须显式支持：使用组件文档化的命名属性，而不是通配 `aria-*` 透传。组件拥有自己的 role 和交互状态。
`click`、`input`、`change` 等浏览器 composed 原生事件仍是主要交互 API。`open-change` 等 kebab-case 自定义事件
仅描述用户操作导致的组件状态变化；程序化赋值 property 不会触发它们。
### 表单关联控件
所有表单控件均参与原生 `FormData`、约束校验、`form.reset()` 和浏览器表单状态恢复。控件会在**首次连接且声明式属性完成初始化后**捕获一次重置默认值；之后的运行时 property 更新不会改写该默认值。祖先 `fieldset` 的禁用状态会禁用交互和校验，但不会改写控件公开的 `disabled` 属性。对于 checkbox/radio group，父 group 是提交、重置和状态恢复的唯一所有者；被管理的子项不会独立提交或恢复状态。
## 所有组件
| 分类 | 组件 |
| --------------- | --------------------------------------------------------- |
| **表单控件** | [``](#web-ui-input) |
| | [``](#web-ui-textarea) |
| | [``](#web-ui-input-number) |
| | [``](#web-ui-select) |
| | [``](#web-ui-autocomplete) |
| | [``](#web-ui-slider) |
| | [``](#web-ui-checkbox) |
| | [``](#web-ui-radio) |
| | [``](#web-ui-switch) |
| | [``](#web-ui-segmented) |
| | [``](#web-ui-checkbox-group) |
| | [``](#web-ui-radio-group) |
| **按钮** | [``](#web-ui-button) |
| | [``](#web-ui-button-group) |
| **浮层 / 模态** | [``](#web-ui-dialog) |
| | [``](#web-ui-drawer) |
| **浮动** | [``](#web-ui-popover) |
| | [``](#web-ui-tooltip) |
| | [``](#web-ui-context-menu) |
| **菜单** | [``](#web-ui-dropdown) |
| | [``](#web-ui-dropdown-item) |
| | [``](#web-ui-dropdown-divider) |
| | [``](#web-ui-dropdown-header) |
| **数据展示** | [``](#web-ui-avatar) |
| | [``](#web-ui-badge) |
| | [``](#web-ui-empty) |
| | [``](#web-ui-icon) |
| | [``](#web-ui-spinner) |
| **布局与工具** | [``](#web-ui-layout) |
| | [``](#web-ui-back-top) |
| | [``](#web-ui-svg-draw-lines) |
| | [``](#web-ui-theme) |
| **通知** | [``](#web-ui-toast) |
| **子项** | [``](#web-ui-option) |
| | [``](#web-ui-segmented-trigger) |
## API 参考
### 表单控件
表单控件声明 `static formAssociated = true`，集成原生 `