SanoUI

Appearance

最佳实践 ​

SanoUI 框架的最佳实践指南，帮助你更好地使用组件库。

🎯 使用原则 ​

1. 优先使用自动初始化 ​

对于简单的静态页面，优先使用 SA.init() 自动初始化，代码更简洁。

html
<!-- ✅ 推荐：自动初始化 -->
<button class="sa-button" data-button data-type="primary">按钮</button>
<div class="sa-alert" data-alert data-type="success" data-title="成功"></div>

<script>
  SA.init('body');
</script>
html
<!-- ❌ 不推荐：过度使用手动初始化 -->
<button id="my-btn"></button>
<div id="my-alert"></div>

<script>
  new SaButton('#my-btn', { type: 'primary', label: '按钮' });
  new SaAlert('#my-alert', { type: 'success', title: '成功' });
</script>

2. 合理划分初始化范围 ​

将需要初始化的组件放在同一个容器中，避免重复初始化。

html
<!-- ✅ 推荐：在特定容器内初始化 -->
<div id="app">
  <button class="sa-button" data-button>按钮</button>
  <div class="sa-alert" data-alert data-type="success">提示</div>
</div>

<script>
  SA.init('#app'); // 只初始化 app 容器内的组件
</script>

3. 及时销毁动态创建的组件 ​

对于动态创建和销毁的组件，记得调用 destroy() 方法释放资源。

javascript
// ✅ 推荐：动态组件记得销毁
function createAndDestroyComponent() {
  const button = new SaButton('#temp-button', {
    type: 'primary',
    label: '临时按钮'
  });
  
  // 使用完毕后销毁
  setTimeout(() => {
    button.destroy();
    document.getElementById('temp-button').remove();
  }, 5000);
}

📋 组件使用规范 ​

表单组件 ​

1. 统一使用 Form 组件管理 ​

将所有表单控件放在 SaForm 组件内，便于统一验证和管理。

html
<!-- ✅ 推荐 -->
<form class="sa-form" id="myForm">
  <div class="sa-form-item">
    <label class="sa-form-item__label">用户名</label>
    <div class="sa-form-item__content">
      <div class="sa-input" data-prop="username"></div>
    </div>
  </div>
</form>

<script>
  const form = new SaForm('#myForm', {
    rules: {
      username: [{ required: true, message: '请输入用户名' }]
    }
  });
  SA.init('#myForm');
</script>

2. 合理使用验证规则 ​

根据实际需求选择验证规则，避免过度验证。

javascript
// ✅ 推荐：合理的验证规则
rules: {
  username: [
    { required: true, message: '请输入用户名' },
    { min: 3, max: 20, message: '用户名长度为 3-20 个字符' }
  ],
  email: [
    { required: true, message: '请输入邮箱' },
    { type: 'email', message: '请输入正确的邮箱格式' }
  ]
}

表格组件 ​

1. 使用服务端分页 ​

对于大量数据，使用 dataFetcher 实现服务端分页。

javascript
// ✅ 推荐：服务端分页
const table = new SaTable('#my-table', {
  columns: [...],
  pagination: {
    pageSize: 10,
    showControls: true
  },
  dataFetcher: async (params) => {
    const response = await fetch(`/api/data?page=${params.page}&pageSize=${params.pageSize}`);
    const result = await response.json();
    return {
      data: result.data,
      total: result.total
    };
  }
});

2. 合理配置列宽 ​

为表格列设置合适的宽度，避免内容溢出。

javascript
// ✅ 推荐：设置列宽
columns: [
  { prop: 'name', label: '姓名', width: 120 }, // 固定宽度
  { prop: 'address', label: '地址' } // 自适应宽度
]

反馈组件 ​

1. 合理选择提示类型 ​

根据场景选择合适的反馈组件。

javascript
// ✅ 成功操作使用 Message
SaMessage.success('操作成功！');

// ✅ 重要提示使用 Alert
new SaAlert('#alert', {
  type: 'warning',
  title: '警告',
  description: '请确认操作'
});

// ✅ 确认操作使用 Dialog
SaDialog.confirm({
  title: '确认删除',
  content: '确定要删除吗？'
});

🎨 样式和主题 ​

1. 使用 CSS 变量定制主题 ​

通过 CSS 变量轻松定制主题色。

css
:root {
  --theme-color: #409EFF; /* 主色 */
  --theme-color-light: rgba(64, 158, 255, 0.1); /* 浅色 */
}

2. 保持样式一致性 ​

使用统一的间距、字体大小等样式规范。

css
/* ✅ 推荐：使用统一的间距变量 */
.container {
  padding: 16px;
  margin-bottom: 20px;
}

.form-item {
  margin-bottom: 20px;
}

⚡ 性能优化 ​

1. 按需加载组件 ​

只加载需要使用的组件，减少包体积。

html
<!-- ✅ 只加载需要的组件 -->
<link rel="stylesheet" href="./sanoui.min.css">
<script src="./sanoui.min.js"></script>

2. 避免重复初始化 ​

同一个元素不要多次初始化。

javascript
// ❌ 错误：重复初始化
SA.init('body');
SA.init('body'); // 重复初始化

// ✅ 正确：只初始化一次
const page = SA.init('body');

3. 批量操作 DOM ​

对于大量组件，使用批量操作减少 DOM 操作。

javascript
// ✅ 推荐：批量创建
const container = document.getElementById('container');
const items = Array.from({ length: 100 }, (_, i) => ({
  label: `选项${i + 1}`,
  value: `option${i + 1}`
}));

items.forEach(item => {
  const el = document.createElement('div');
  container.appendChild(el);
  new SaTag(el, { text: item.label });
});

🔒 安全性 ​

1. 验证用户输入 ​

对用户输入进行验证，防止 XSS 攻击。

javascript
// ✅ 推荐：验证输入
const form = new SaForm('#myForm', {
  rules: {
    username: [
      { required: true },
      { pattern: /^[a-zA-Z0-9_]+$/, message: '只能包含字母、数字和下划线' }
    ]
  }
});

2. 使用 HTTPS ​

生产环境使用 HTTPS 传输数据。

📱 响应式设计 ​

1. 使用相对单位 ​

使用相对单位（rem、em、%）而非固定像素。

css
/* ✅ 推荐：使用相对单位 */
.container {
  width: 100%;
  max-width: 1200px;
  padding: 1rem;
}

2. 移动端适配 ​

考虑移动端使用体验，合理设置组件尺寸。

javascript
// ✅ 推荐：根据屏幕尺寸调整
const isMobile = window.innerWidth < 768;
const table = new SaTable('#my-table', {
  columns: [...],
  size: isMobile ? 'small' : 'default'
});

🐛 错误处理 ​

1. 优雅的错误提示 ​

使用统一的错误提示方式。

javascript
// ✅ 推荐：统一的错误处理
async function fetchData() {
  try {
    const response = await fetch('/api/data');
    if (!response.ok) {
      throw new Error('请求失败');
    }
    const data = await response.json();
    return data;
  } catch (error) {
    SaMessage.error(error.message || '操作失败');
    console.error(error);
  }
}

2. 验证组件是否存在 ​

在使用组件前检查组件是否已加载。

javascript
// ✅ 推荐：检查组件是否存在
function initComponents() {
  if (typeof SaButton === 'undefined') {
    console.error('SaButton 组件未加载');
    return;
  }
  new SaButton('#my-button', { type: 'primary' });
}

🔧 代码组织 ​

1. 模块化组织 ​

按功能模块组织代码，保持代码清晰。

javascript
// ✅ 推荐：模块化组织
// form-handler.js
export function initForm() {
  const form = new SaForm('#my-form', {
    rules: { /* ... */ }
  });
  SA.init('#my-form');
  return form;
}

// table-handler.js
export function initTable() {
  const table = new SaTable('#my-table', {
    columns: [ /* ... */ ]
  });
  return table;
}

// main.js
import { initForm } from './form-handler.js';
import { initTable } from './table-handler.js';

initForm();
initTable();

2. 统一配置 ​

将通用配置提取到配置文件。

javascript
// ✅ 推荐：统一配置
const config = {
  table: {
    pageSize: 10,
    stripe: true,
    border: false
  },
  form: {
    labelWidth: '100px',
    labelPosition: 'right'
  }
};

const table = new SaTable('#my-table', {
  ...config.table,
  columns: [...]
});

📚 文档和注释 ​

1. 添加必要的注释 ​

为复杂逻辑添加注释说明。

javascript
// ✅ 推荐：添加注释
/**
 * 初始化用户表单
 * @param {string} formId - 表单元素 ID
 * @returns {SaForm} 表单实例
 */
function initUserForm(formId) {
  const form = new SaForm(formId, {
    rules: {
      // 用户名验证规则
      username: [
        { required: true, message: '请输入用户名' }
      ]
    }
  });
  return form;
}

2. 保持文档更新 ​

及时更新文档，确保文档与代码一致。

🎓 学习资源 ​

  • 查看 组件文档 了解各个组件的详细用法
  • 查看 示例 了解更多使用场景

💡 常见问题 ​

Q: 何时使用自动初始化，何时手动创建？ ​

A:

  • 自动初始化：适合静态页面、简单场景、快速原型
  • 手动创建：适合动态内容、复杂交互、需要精细控制

Q: 如何优化组件性能？ ​

A:

  • 避免重复初始化
  • 合理使用虚拟滚动（Table 组件）
  • 批量操作 DOM
  • 按需加载组件

Q: 如何处理大量数据？ ​

A:

  • 使用服务端分页
  • 使用 Table 的 dataFetcher 函数
  • 考虑使用虚拟滚动

Q: 如何自定义主题？ ​

A:

  • 使用 CSS 变量覆盖默认主题色
  • 修改 variables.css 文件
  • 使用主题管理器 ThemeManager

🔗 相关链接 ​

Released under the MIT License.

Copyright © 2025 SanoUI