@ui18n/selector-web/README.md

🌐 零依赖Web Components语言选择器 - 支持所有框架和浏览器的通用组件

# @ui18n/selector-web

Web原生语言选择器组件，支持现代浏览器的自定义元素标准。

## ⚠️ Experimental Package

**This package is currently in experimental stage. API may change in future releases.**

**For production use, we recommend:**
- Use `@ui18n/core` with CDN for pure JavaScript projects
- Wait for Phase 1 to stabilize before using framework packages
- Follow our [roadmap](https://github.com/iron-wayne/UI18N-OSS#roadmap) for updates

**Why experimental?**
We are focusing on Phase 1 (pure JavaScript + CDN) following the Lean Beachhead Strategy. Framework packages will be stabilized in Phase 2 after core functionality is validated.

---

## 安装

```bash
npm install @ui18n/selector-web
```

## 快速开始

### HTML方式

```html
<!-- 引入组件 -->
<script type="module" src="@ui18n/selector-web"></script>

<!-- 使用组件 -->
<ui18n-language-selector
  languages="zh-CN,en,ja,ko"
  current="zh-CN"
  show-flags="true">
</ui18n-language-selector>
```

### JavaScript方式

```javascript
import '@ui18n/selector-web';

// 动态创建选择器
const selector = document.createElement('ui18n-language-selector');
selector.setAttribute('languages', 'zh-CN,en,ja');
selector.setAttribute('current', 'zh-CN');
selector.setAttribute('show-flags', 'true');

document.body.appendChild(selector);

// 监听语言变化
selector.addEventListener('language-change', (event) => {
  console.log('语言已切换到:', event.detail.language);
});
```

## API 参考

### ui18n-language-selector

#### 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `languages` | string | '' | 支持的语言列表，逗号分隔 |
| `current` | string | '' | 当前选中的语言 |
| `show-flags` | boolean | false | 是否显示国旗图标 |
| `show-labels` | boolean | true | 是否显示语言标签 |
| `theme` | string | 'light' | 主题样式 (light/dark) |

#### 事件

- `language-change` - 语言切换时触发
- `selector-ready` - 组件初始化完成时触发

#### 方法

- `setLanguage(language)` - 程序化设置语言
- `getAvailableLanguages()` - 获取可用语言列表
- `refresh()` - 刷新组件状态

## 样式自定义

```css
ui18n-language-selector {
  --ui18n-selector-bg: #ffffff;
  --ui18n-selector-color: #333333;
  --ui18n-selector-border: #ddd;
  --ui18n-selector-hover: #f5f5f5;
}

/* 暗色主题 */
ui18n-language-selector[theme="dark"] {
  --ui18n-selector-bg: #2d2d2d;
  --ui18n-selector-color: #ffffff;
  --ui18n-selector-border: #555;
  --ui18n-selector-hover: #3d3d3d;
}
```

## 特性

- 🌐 支持100+语言
- 🎨 完全可定制样式
- 📱 响应式设计
- ⚡ 轻量级 (~5KB gzipped)
- 🔧 零依赖
- 🌍 国际化友好

## 浏览器支持

- Chrome >= 54
- Firefox >= 63
- Safari >= 10.1
- Edge >= 79

## 许可证

MIT License

## 贡献

欢迎提交 Pull Request 和 Issue！