b24-ui-nuxt

Bitrix24 UI

基于 Reka UI + Tailwind CSS + Tailwind Variants 构建的 Vue 组件库。适用于 Nuxt、Vue（Vite）、Laravel（Vite + Inertia）和 AdonisJS（Vite + Inertia）。

LLMs.txt

需要了解组件接受哪些内容或其 API 如何工作（属性、插槽、事件、完整文档、示例）时，请使用 Bitrix24 UI 文档；如果尚未配置，请添加该文档。本技能将教你何时使用哪个组件以及如何构建得更好。

核心规则（始终适用）

1. 始终使用 B24App 包裹应用——这是使用 toast、工具提示和程序化叠加层的必要条件。支持用于 i18n 的 locale 属性。
2. 始终使用语义颜色——例如 text-description、bg-elevated、border-muted 等。切勿使用 text-gray-500 这类原始 Tailwind 调色板颜色。
3. 读取生成的主题文件以了解插槽名称——Nuxt：.nuxt/b24ui/<component>.ts；Vue：node_modules/.b24ui-nuxt/b24ui/<component>.ts。这些文件展示了任意组件的所有插槽、变体和默认类。
4. 覆盖优先级（从高到低）：b24ui 属性 / class 属性 → 全局配置 → 主题默认值。
5. 通过 图标指南 查找图标——该指南会根据自然语言描述推荐合适的导入项。

如何使用此技能

根据任务，在编写代码之前加载相关参考文件。不要全部加载，只加载所需内容。

参考文件

指南——设计决策与约定：

• design-system — 语义颜色、主题、品牌自定义、变体、b24ui 属性
• component-selection — 选择决策矩阵：何时使用 Modal 而不是 Slideover、Select 而不是 SelectMenu、Toast 而不是 Alert 等
• conventions — 编码模式、插槽命名、items 数组、组合式函数、键盘快捷键
• forms — 表单验证、字段布局、错误处理、Standard Schema
• icons — 导入并使用图标

布局——完整的页面结构模式：

• landing — 落地页
• dashboard — 带侧边栏和面板的管理界面

方案——常见任务的完整模式：

• data-tables — 带筛选、分页、排序和选择功能的表格
• overlays — 模态框、侧滑面板、抽屉、命令面板、信息弹出框
• navigation — 页眉、侧边栏、面包屑、标签页
• card-pickers — 用于选择设置变体或切换功能的图标与描述卡片网格（B24PageCardGroup）
• settings — 设置布局：何时使用 Switch、Radio、Checkbox 或 PageCardGroup，以及带预览图片、描述和“了解更多”链接的丰富 card 变体方案
• detail-panel — 实体信息侧边栏：在主视图旁展示元数据、可切换的设置和分组内容区块
• task-form — 单列任务/问题表单，组合使用 B24Editor、负责人字段、日期选择器，以及一行可换行的次要操作

快速参考：

• components — 按类别整理的组件索引，方便查找合适的组件名称

路由表

任务	加载这些参考资料
为 Bitrix24 构建应用 / 仪表盘 / 管理界面	conventions、component-selection、dashboard
构建落地页	design-system、conventions、landing
添加设置页面	conventions、forms、settings
选择一个选项 / 在每个选项都需要预览图片、多行说明和内联“了解更多”链接时切换多个选项——布局选择器、带截图的套餐选择器	conventions、settings
创建登录 / 注册表单	conventions、forms、component-selection
在表格中显示数据	conventions、component-selection、data-tables
添加聊天界面	conventions、components（§ Chat）
添加模态框、侧滑面板或抽屉	conventions、component-selection、overlays
构建网站导航	conventions、component-selection、navigation
渲染 Markdown	component-selection、components（§ Prose 和 § Content）
从一小组选项中选择一个（或切换多个），且每个选项都需要图标和一句说明——设置变体、功能标记、“你想构建什么？”向导步骤	conventions、component-selection、card-pickers
添加富文本编辑器	conventions、components（§ Editor）
构建包含富文本描述、受指派人和截止日期的任务 / 问题表单	conventions、forms、task-form
构建实体信息侧边栏——频道信息、CRM 记录详情、“关于此项”	conventions、component-selection、detail-panel
为按钮、项目或空状态查找图标	icons
通用 UI 工作	conventions、component-selection

安装

Nuxt

pnpm add @bitrix24/b24ui-nuxt @bitrix24/b24icons-vue tailwindcss

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@bitrix24/b24ui-nuxt'],
  css: ['~/assets/css/main.css']
})

/* app/assets/css/main.css */
@import "tailwindcss";
@import "@bitrix24/b24ui-nuxt";

<template>
  <B24App>
    <NuxtPage />
  </B24App>
</template>

Vue（Vite）

pnpm add @bitrix24/b24ui-nuxt @bitrix24/b24icons-vue tailwindcss

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    bitrix24UIPluginVite()
  ]
})

// src/main.ts
import './assets/main.css'
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import b24UiPlugin from '@bitrix24/b24ui-nuxt/vue-plugin'
import App from './App.vue'

const app = createApp(App)
const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(b24UiPlugin)
app.mount('#app')

/* src/assets/css/main.css */
@import "tailwindcss";
@import "@bitrix24/b24ui-nuxt";

<template>
  <B24App>
    <RouterView />
  </B24App>
</template>

在 index.html 中的根 <div id="app"> 上添加 class="isolate"。 对于 Inertia：在 vite.config.ts 中使用 b24ui({ router: 'inertia' })。