press-pix/common/styles/pubgm/direction-base-usage-example.md

基于 PixUI 的 Press 组件库

# direction-base.less 使用指南

## 📖 概述

`direction-base.less` 提供了 LTR/RTL 双向布局支持的混合宏集合。由于已从 webpack 全局注入中移除，现在需要在每个使用 RTL 混合宏的组件样式文件中**手动导入**。

---

## 🎯 使用方法

### 1️⃣ 在组件样式文件中导入

```less
// 在组件的 .less 文件顶部导入
@import '../../../styles/direction-base.less';

// 然后使用混合宏
.container {
  .margin-inline-start(10px);
  .padding-inline-end(20px);
  .text-align-start();
}
```

### 2️⃣ 根据文件位置调整导入路径

```less
// 如果组件在 pages/home/css/home.less
@import '../../../styles/direction-base.less';

// 如果组件在 components/Button/css/Button.less
@import '../../../../styles/direction-base.less';

// 如果组件在 pages/watch-list/component/WatchCard/css/WatchCard.less
@import '../../../../../styles/direction-base.less';
```

---

## 📦 可用的混合宏

### 文本对齐
- `.text-align-start()` - 文本起始对齐（LTR: left, RTL: right）
- `.text-align-end()` - 文本结束对齐（LTR: right, RTL: left）

### Flex 布局
- `.flex-direction-row()` - Flex 行方向（LTR: row, RTL: row-reverse）
- `.flex-direction-row-reverse()` - Flex 行反向
- `.justify-content-start()` - 主轴起始对齐
- `.justify-content-end()` - 主轴结束对齐
- `.align-content-start()` - 换行起始对齐
- `.align-content-end()` - 换行结束对齐

### 外边距（Margin）
- `.margin-inline-start(@value)` - 行内起始外边距（LTR: margin-left, RTL: margin-right）
- `.margin-inline-end(@value)` - 行内结束外边距（LTR: margin-right, RTL: margin-left）

### 内边距（Padding）
- `.padding-inline-start(@value)` - 行内起始内边距（LTR: padding-left, RTL: padding-right）
- `.padding-inline-end(@value)` - 行内结束内边距（LTR: padding-right, RTL: padding-left）

### 边框（Border）
- `.border-inline-start(@value)` - 行内起始边框（LTR: border-left, RTL: border-right）
- `.border-inline-end(@value)` - 行内结束边框（LTR: border-right, RTL: border-left）
- `.border-inline-start-width(@value)` - 行内起始边框宽度
- `.border-inline-end-width(@value)` - 行内结束边框宽度
- `.border-inline-start-style(@value)` - 行内起始边框样式
- `.border-inline-end-style(@value)` - 行内结束边框样式
- `.border-inline-start-color(@value)` - 行内起始边框颜色
- `.border-inline-end-color(@value)` - 行内结束边框颜色

### 定位（Position）
- `.inset-inline-start(@value)` - 行内起始定位（LTR: left, RTL: right）
- `.inset-inline-end(@value)` - 行内结束定位（LTR: right, RTL: left）

---

## 🔄 RTL 模式切换

在 JavaScript 中根据语言动态添加类名：

```javascript
// 判断是否为 RTL 语言
const isRTLLanguage = ['ar', 'he', 'fa', 'ur'].includes(currentLanguage);

// 切换 RTL 模式
document.documentElement.classList.toggle('rtl-map', isRTLLanguage);
```

---

## ✅ 完整示例

```less
// components/Card/css/Card.less
@import '../../../styles/direction-base.less';

.card {
  display: flex;
  .flex-direction-row();
  .padding-inline-start(20px);
  .padding-inline-end(10px);
  
  .card-icon {
    .margin-inline-end(12px);
  }
  
  .card-title {
    .text-align-start();
  }
  
  .card-action {
    position: absolute;
    .inset-inline-end(10px);
  }
}
```

编译后的 CSS：

```css
/* LTR 默认样式 */
.card {
  display: flex;
  flex-direction: row;
  padding-left: 20px;
  padding-right: 10px;
}

.card .card-icon {
  margin-right: 12px;
}

.card .card-title {
  text-align: left;
}

.card .card-action {
  position: absolute;
  right: 10px;
}

/* RTL 覆盖样式 */
.rtl-map .card {
  flex-direction: row-reverse;
  padding-left: 10px;
  padding-right: 20px;
}

.rtl-map .card .card-icon {
  margin-right: 0;
  margin-left: 12px;
}

.rtl-map .card .card-title {
  text-align: right;
}

.rtl-map .card .card-action {
  right: auto;
  left: 10px;
}
```

---

## ⚠️ 注意事项

1. **必须手动导入**：每个使用 RTL 混合宏的样式文件都需要导入 `direction-base.less`
2. **路径正确性**：根据文件位置调整相对路径
3. **避免物理属性**：不要直接使用 `left`/`right`/`margin-left` 等物理属性，统一使用混合宏
4. **CSS Modules 兼容**：混合宏完全兼容 CSS Modules，作用域处理正确

---

## 🆚 对比：全局注入 vs 手动导入

| 对比项 | 全局注入（之前） | 手动导入（现在） |
|--------|-----------------|-----------------|
| **导入方式** | webpack 自动注入 | 每个文件手动导入 |
| **代码冗余** | ✅ 零冗余 | ❌ 每个文件都要导入 |
| **路径管理** | ✅ 无需关心 | ❌ 需要计算相对路径 |
| **依赖透明** | ❌ 隐式依赖 | ✅ 显式依赖 |
| **维护成本** | ✅ 极低 | ❌ 较高 |
| **性能** | ✅ 更优 | ⚠️ 略差 |

---

## 💡 最佳实践

1. **统一导入位置**：在样式文件顶部导入
2. **使用绝对路径别名**（如果配置了）：`@import '~@/styles/direction-base.less'`
3. **按需使用**：只在需要 RTL 支持的组件中导入
4. **代码审查**：确保所有使用混合宏的文件都已导入

---

## 🔧 如果需要恢复全局注入

编辑 `.pixiderc/webpack.js`：

```javascript
const GLOBAL_LESS_FILES = [
  '../src/local-component/ui/styles/direction-base.less', // 取消注释
].map(relativePath => 
  path.resolve(__dirname, relativePath).replace(/\\/g, '/')
);
```

然后删除所有组件中的手动导入语句。