kivii-public-components

kivii-public-components

VoiceInputButton

语音输入按钮集成了浏览器录音、Sherpa-ONNX Silero VAD 静音检测和音频转写。

基本用法

<script setup lang="ts">
import { ref } from 'vue'
import { VoiceInputButton } from 'kivii-public-components'

const value = ref('')
const transcriptionEndpoint = import.meta.env.DEV
  ? '/asr-api/audio/transcriptions'
  : 'https://api.kivii.com/v1/audio/transcriptions'
</script>

<template>
  <VoiceInputButton
    v-model="value"
    :endpoint="transcriptionEndpoint"
    :auto-stop-seconds="6"
    @error="console.error"
    @transcribed="text => console.log('转写完成', text)"
  />
</template>

Vite 资源插件

语音组件依赖 sherpa-vad 运行资源。在宿主项目的 vite.config.ts 注册资源插件， 插件会在开发环境直接提供文件，并在生产构建时自动复制到 /sherpa-vad/：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { kiviiVoiceAssets } from 'kivii-public-components/vite'

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

插件在 Vite 开发和预览服务器中默认添加 SharedArrayBuffer、WASM Worker 所需的 跨域隔离响应头，VAD 资源响应也会包含这些标头：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: credentialless
Cross-Origin-Resource-Policy: same-origin

无法提供 SharedArrayBuffer 或跨域隔离的浏览器会自动切换为 Web Audio 兼容录音模式，麦克风采集和转写仍可使用；Sherpa VAD 可用时则继续提供更准确的语音分段。

如果部署平台统一管理这些响应头，可以使用 kiviiVoiceAssets({ crossOriginHeaders: false })。自定义资源路径时，需要让插件的 publicPath 与组件的 vad-base-url 保持一致。

自定义路径示例：

// vite.config.ts
kiviiVoiceAssets({ publicPath: '/assets/kivii-vad/' })

<VoiceInputButton vad-base-url="/assets/kivii-vad/" />

生产部署注意：插件负责把 VAD 文件复制进构建产物，但无法修改 Nginx、IIS 或 CDN 的 HTTP 响应配置。生产服务器必须为页面及 /sherpa-vad/ 资源配置上述三个响应头， 否则浏览器会拦截 WASM Worker，组件将显示错误状态。

VoiceInputButton Props

默认生产转写接口为 https://api.kivii.com/v1/audio/transcriptions。开发环境如需通过 Vite 代理隐藏 API Key，应将 endpoint 设置为代理路径，并由 server.proxy 注入认证头。

Events

组件通过模板 ref 暴露 cancel() 方法，可主动取消当前录音：

<script setup lang="ts">
import { ref } from 'vue'
import { VoiceInputButton } from 'kivii-public-components'

const voiceButton = ref<InstanceType<typeof VoiceInputButton>>()

function cancelVoiceInput() {
  voiceButton.value?.cancel()
}
</script>

<template>
  <VoiceInputButton ref="voiceButton" />
</template>

运行要求

• Vue 3.5 或更高版本。
• 支持 Web Audio API 和 getUserMedia 的现代浏览器。
• 除 localhost 外，麦克风访问需要 HTTPS 安全上下文。
• SharedArrayBuffer 与跨域隔离用于启用 Sherpa VAD；不可用时自动进入兼容录音模式。
• 浏览器首次使用时，用户必须授权麦克风权限。

基于 Vue 3 + Naive UI 的公共组件库，提供开箱即用的数据表格组件，支持搜索、分页、列配置、增删改等能力。

特性

• 自包含设计，无需宿主安装或配置 Naive UI
• 支持动态列配置、搜索字段配置
• 内置分页、排序、筛选
• 支持自定义动作、数据转换规则
• 支持暗色/亮色主题

安装

# npm
npm install kivii-public-components

# pnpm
pnpm add kivii-public-components

# yarn
yarn add kivii-public-components

前置依赖：宿主项目需要安装 Vue 3（组件本身已内置 Naive UI，无需额外安装）。

pnpm add vue

快速开始

1. 引入样式

在项目入口文件（main.ts 或根组件）中引入 CSS：

import 'kivii-public-components/style'

2. 使用组件

<template>
  <TableIndex :uiConfig="config" />
</template>

<script setup lang="ts">
import { TableIndex } from 'kivii-public-components'

const config = {
  Type: 'YourApp.Entities.Invoice',
  InternalCode: '发票管理',
  IsDefault: true,
  InitQuery: '/api/Invoice/Query.json',
  GetUrl: '/api/UiConfig/Get.json',
  SetUrl: '/api/UiConfig/Set.json',
}
</script>

API

TableIndex Props

UiConfig 配置项

接口约定

组件内部使用 axios 调用接口，需后端按以下格式返回数据。

查询接口 InitQuery（GET）

{
  "Data": [...],
  "Total": 100
}

列结构接口 /Server/Entity/{Type}（GET）

[
  { "Field": "Name", "Label": "名称", "DataType": "string" },
  { "Field": "Amount", "Label": "金额", "DataType": "number" }
]

完整示例

<template>
  <div style="padding: 16px;">
    <TableIndex :uiConfig="tableConfig" />
  </div>
</template>

<script setup lang="ts">
import { TableIndex } from 'kivii-public-components'
import 'kivii-public-components/style'

const tableConfig = {
  Type: 'YourApp.Entities.Order',
  InternalCode: '订单列表',
  IsDefault: true,
  InitQuery: '/api/Order/Query.json',
  GetUrl: '/api/UiConfig/Get.json',
  SetUrl: '/api/UiConfig/Set.json',
  InitDelete: '/api/Order/Delete.json',
  CreateVueUrl: '/forms/orderForm.vue',
}
</script>

注意事项

接口代理

组件内部接口请求使用相对路径，本地开发时请在宿主项目的 Vite 配置中设置代理：

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'https://your-api-server.com',
        changeOrigin: true,
      },
    },
  },
})

无需配置 Naive UI Provider

本组件已在内部封装了 NConfigProvider、NMessageProvider、NDialogProvider，宿主项目无需安装或注册 Naive UI，直接使用即可。

版本记录

License

MIT