kintone-plugins/kintone-vue-template
Template
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix

Browse Source
This commit is contained in:
薛家豪
2025-10-17 14:34:31 +08:00
parent 7ddaeb4bf8
commit a9074aca30
10 changed files with 290 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
README.md
View File

@@ -14,6 +14,7 @@
- [@kintone/plugin-uploader](https://cybozu.dev/ja/kintone/sdk/development-environment/plugin-uploader/)
- [@kintone/dts-gen](https://cybozu.dev/ja/kintone/sdk/library/dts-gen/)
# 使用步骤
首先进行安装
@@ -75,6 +76,7 @@ npm install # 或 yarn
}
```
# 编译流程
- `build` 会生成 `dist` 文件夹，以及 `plugin.zip` 文件
@@ -100,43 +102,9 @@ npm run upload # 或 yarn upload
npm run build-upload # 或 yarn build-upload
```
# 开发说明
## 项目结构
```
├── src
│ ├── components
│ │ ├── basic
│ │ │ ├── PluginInput.vue
│ │ │ └── PluginLabel.vue
│ │ └── Config.vue
│ ├── css
│ │ ├── 51-modern-default.css
│ │ └── config.css
│ ├── i18n
│ │ ├── lang
│ │ │ ├── en.ts
│ │ │ └── ja.ts
│ │ └── index.ts
│ ├── js
│ │ ├── desktop.ts
│ │ └── mobile.ts
│ ├── types
│ │ ├── index.d.ts
│ │ ├── model.d.ts
│ │ └── my-kintone.d.ts
│ ├── main.ts
│ └── manifest.json
├── README.md
├── components.d.ts
├── env.d.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts
```
当前模板中已经有一个案例，可以参考并且修改。
1. 对于 Config 页面，请修改 `components/Config.vue`
@@ -145,20 +113,76 @@ npm run build-upload # 或 yarn build-upload
这三个文件是强制指定的，请不要修改。
### 关于 Config 页面
## 项目结构
```shell
├── src
│ ├── components # config 页面
│ │ ├── basic
│ │ │ ├── PluginInput.vue
│ │ │ └── PluginLabel.vue
│ │ └── Config.vue # config 页面入口
│ ├── css
│ │ ├── 51-modern-default.css # config 页面额外引用的样式 css
│ │ ├── config.css # config 页面引用的 css
│ │ ├── desktop.css # desktop app 页面引用的 css
│ │ └── mobile.css # mobile app 页面引用的 css
│ ├── i18n # i18n 语言包相关
│ │ ├── lang
│ │ │ ├── en.ts
│ │ │ └── ja.ts
│ │ └── index.ts
│ ├── js
│ │ ├── desktop.ts # desktop app 页面入口
│ │ └── mobile.ts # mobile app 页面入口
│ ├── types
│ │ ├── index.d.ts
│ │ ├── model.d.ts
│ │ └── my-kintone.d.ts # kintone 相关的 ts 类型
│ ├── main.ts
│ └── manifest.json # kintone plugin 需要的配置
├── .eslintrc.js
├── .gitignore
├── .prettierrc
├── components.d.ts # vue 中自动 import，build 的时候生成
├── env.d.ts # vue 类型定义
├── index.html
├── package.json
├── private.ppk # 当前 plugin 密钥，首次 build 自动生成
├── README.md
├── tsconfig.json
└── vite.config.ts # 主要的 vite 配置
└── vite.desktop.config.ts # 用于打包 desktop 文件的配置
└── vite.mobile.config.ts # 用于打包 mobile 文件的配置
```
## 关于 Config 页面开发
只有 **Config 页面** 的开发可以使用 Vue Template，其他页面请使用 `js` 文件。
基本上和 Vue 开发没有区别，但是有以下一些限制：
1. CSS 样式只能使用 `css` 文件
2. `kintone-ui-component` 库有一些限制
2. [`kintone-ui-component` 库有一些限制](#对于-kintone-ui-component-库的限制)
### 关于 CSS
## 关于 desktop/mobile 的 app 页面开发
1. 暂时不支持在 Vue Template 中创建，**只能在 `css` 文件夹下新建 css 文件**
2. 目前在 `config` 页面引入了 `51-modern-default.css`，里面存放了 kintone 的一些样式
- 如果不需要使用就在 `manifest.json` 中删除
desktop/mobile 的 js 会被 `vite` 使用 `lib` 模式打包，从而将所有 import 合并到同一个文件里面。
## 关于 CSS 开发
> 暂时不支持在 Vue Template 中创建 css，**只能在 `css` 文件夹下新建 css 文件**
`/css` 目录下分别对应了不同环境的 css 样式
- `config.css` - config 页面引用的 css
- `desktop.css` - desktop app 页面引用的 css
- `mobile.css` - mobile app 页面引用的 css
另外，在 `config` 页面引入了 `51-modern-default.css`，里面存放了 kintone 的一些样式
- 如果不需要使用就在 `manifest.json` 中删除
```diff
"config": {
"html": "html/config.html",
@@ -176,14 +200,195 @@ npm run build-upload # 或 yarn build-upload
```
## 关于 i18n
###
在 desktop/mobile：
```ts
import i18n from '@/i18n';
const { t } = i18n.global;
console.log(t('config.button.label'));
```
在 vue：
```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
const { t } = useI18n();
console.log(t('config.button.label'));
```
**支持 Vue 页面**，
不支持 Vue 页面，
# 对于 `kintone-ui-component` 库的限制
## desktop/mobile 页面
在 desktop/mobile 的 app 页面中，import 的时候建议使用 lib 下的路径，按需导入
```js
// 建议
import { Button } from 'kintone-ui-component/lib/button';
// 下面的方式不太建议，都会引入所有的组件
import { Button } from 'kintone-ui-component';
import kuc from 'kintone-ui-component';
```
## config 页面
由于 kuc 只提供了 umd 文件，所以对于 vue 页面，有比较多的限制
## 对于 `kintone-ui-component` 库的限制
### 基本使用方式
v-model 语法糖无法使用
在 `<template>` 中使用 `<kuc-*>` 组件时：
1. **不需要写 kuc 文档中所说的版本号**
2. 不需要在 `<script>` 中手动 import
这些已经在 `vite.config.ts` 中已经自动处理了。
```ts
<kuc-text :value="modelValue" @change="updateValue" />
```
而对于在 `<script>` 中使用到的 ts type，和在 desktop/mobile 一样，请使用 `lib` 下的组件
```ts
import type { TextInputEventDetail } from 'kintone-ui-component/lib/text';
```
### v-model 语法糖无法使用
毕竟不是专门为 vue 开发的，所以默认不能使用 v-model 语法糖
需要自行创建 emit 事件（参考 `/src/components/basic/PluginInput.vue` ）
```vue
<template>
<kuc-text :value="modelValue" @change="updateValue" />
</template>
<script setup lang="ts">
import type { KucEvent } from '@/types/my-kintone';
import type { TextInputEventDetail } from 'kintone-ui-component/lib/text';
import { defineProps, defineEmits } from 'vue';
// KUC Text 组件不支持 v-model 语法，因此需要进行包装以支持双向绑定
const props = defineProps<{
modelValue: string;
}>();
const emit = defineEmits<{
(e: 'update:modelValue', value: string): void;
}>();
/**
* 处理 v-model 事件
*/
const updateValue = ({ detail }: KucEvent<TextInputEventDetail>) => {
emit('update:modelValue', detail.value || '');
};
</script>
```
### 封装组件的问题
当为了解决 v-model 的问题，可能会需要封装组件。我们会使用 `v-bind` 来避免手动来加 kuc 组件的所有属性。（参考 `/src/components/basic/PluginInput.vue` ）
```vue
<template>
<kuc-text v-bind="textProps" />
</template>
<script setup lang="ts">
import type { TextProps } from 'kintone-ui-component/lib/text';
import { defineProps, computed } from 'vue';
const props = defineProps<TextProps & {
modelValue: string; // 用于解决 v-model
}>();
/**
* 生成传递给 KUC Text 组件的属性对象
*/
const textProps = computed<TextProps>(() => {
return {
...props,
className: "kuc-text-input " + ${props.className}, // 添加基础样式类
};
</script>
```
但是有的 `boolean` 类型的属性，会被默认设置为 `false`，导致问题
- 比如 `visible: false` 就看不到组件了
所以需要手动将这些 `boolean` 属性设置为 `undefined`
```ts
const props = withDefaults(defineProps<TextProps & {
modelValue: string;
}>(), {
// 布尔值的默认值处理，设置为 undefined 表示未定义，否则默认会是 false
disabled: undefined,
requiredIcon: undefined,
visible: undefined,
});
const textProps = computed<TextProps>(() => {
const baseProps = {
...props,
className: "kuc-text-input " + ${props.className}, // 添加基础样式类
};
// 移除值为 undefined 的属性，确保只传递有效属性
return Object.fromEntries(Object.entries(baseProps).filter(([_, value]) => value !== undefined)) as TextProps;
});
```
### 关于 spinner
使用 spinner 的时候，如果想要限制在某一个组件上（`:container` 属性），直接使用是不行的，它只会加在 `document.body` 上
不知道为啥，当它创建的时候不会用到 `:container` 参数，即使 HTMLNode 是可见的
所以可以使用 `v-show` 先让它隐藏
> 理论上来说，spinner 使用 new kucs.spinner() 创建更符合习惯，但是我不太想引入 `kuc.min.js` 文件……
```vue
<template>
<div id="main-area" ref="mainArea">
</div>
<!-- 必须使用 v-show 让 spinner dom 创建的时候不显示 -->
<kuc-spinner :container="mainArea" v-show="loading" ref="spinner"></kuc-spinner>
</template>
<script setup lang="ts">
const loading = ref(false);
const mainArea = shallowRef<HTMLElement | null>(null);
const spinner = shallowRef<Spinner | null>(null);
onMounted(async () => {
// 等待页面完全渲染后再显示加载状态，实现更平滑的用户体验
nextTick(async () => {
loading.value = true;
// ...
// 模拟加载时间，展示 spinner 效果
await new Promise((resolve) => setTimeout(resolve, 1000));
loading.value = false;
});
});
// 监听加载状态变化，控制 spinner 显示/隐藏
watch(loading, (load) => {
load ? spinner.value?.open() : spinner.value?.close();
});
</script>
```