QXS-BNS

Appearance

本页导航

安装指南 ​

如果你还没决定接哪一组能力，先从分包安装看起。
QXS-BNS 当前推荐按模块选包，而不是一次性把所有能力都拉进项目。

选择安装包 ​

loading

选择导入方式 ​

安装完成后，再决定你要用子入口按需引入，还是直接整包接入。
这个顺序更接近真实项目的接入流程。

loading

环境要求 ​

环境版本要求说明
Node.js>= 20.11.0推荐使用当前 LTS
Vue>= 3.5.0用于 Vue 宿主和文档站
TypeScript>= 5.5.0可选，但强烈推荐
包管理器pnpm >= 9推荐使用 pnpm

推荐安装 ​

bash
pnpm add @qxs-bns/components
pnpm add @qxs-bns/utils
pnpm add @qxs-bns/hooks
pnpm add @qxs-bns/directives

Components 包定位 ​

@qxs-bns/components 现在提供的是跨框架 Web Components，核心覆盖：

  • 题目编辑、分页边界和运行时 helper
  • qxs-icon
  • qxs-fixed-action-bar
  • qxs-photo-crop-tool
  • qxs-file-upload
  • qxs-image-upload
  • qxs-data-chart
  • qxs-editor

如果你已经在 Vue、React、原生 HTML 或混合宿主里工作，都统一使用这一套入口。

推荐导入方式 ​

1. 子入口按需引入 ​

ts
import '@qxs-bns/components/icon'
import '@qxs-bns/components/data-chart'
import '@qxs-bns/components/image-upload'

2. 整包接入 ​

ts
import '@qxs-bns/components'

3. helper 命名导入 ​

ts
import '@qxs-bns/components'
import {
  collectSubjectElements,
  serializeSubjectElements,
  validateSubjectElements,
} from '@qxs-bns/components'

Vite 项目配置 ​

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

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: tag => tag.startsWith('qxs-'),
        },
      },
    }),
  ],
})

TypeScript 配置 ​

如果你在 Vue / React 宿主里直接操作自定义元素实例，建议确保 DOM 类型包含自定义元素定义：

json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}

Vue 最小接入 ​

vue
<script setup lang="ts">
import '@qxs-bns/components/image-upload'

const fileList = [
  {
    url: '/demo-cover.png',
    name: 'demo-cover.png',
  },
]
</script>

<template>
  <qxs-image-upload
    action="/api/upload"
    :file-list.prop="fileList"
    :limit.prop="1"
  />
</template>

React 最小接入 ​

tsx
import '@qxs-bns/components/fixed-action-bar'

export default function Page() {
  return (
    <qxs-fixed-action-bar padding="12">
      <button type="button">保存</button>
      <button type="button">提交</button>
    </qxs-fixed-action-bar>
  )
}

原生 HTML 最小接入 ​

html
<script type="module">
  import '@qxs-bns/components/icon'
</script>

<qxs-icon icon="ep:home-filled" size="24" color="#3d61e3"></qxs-icon>

注意事项 ​

  • 对象和数组这类复杂值，优先通过 DOM property 传入。
  • 在 Vue 模板里，复杂值建议使用 .prop。
  • 如果宿主要覆盖样式，优先使用 ::part(...)，不要依赖组件内部 DOM 结构。
  • 题目场景优先让宿主直接维护最终提交数据，运行时 helper 只负责校验、分页和序列化。

下一步 ​