refactoring

2025-10-17 14:34:26 +08:00
parent 8e40f9f0e6
commit 7ddaeb4bf8
16 changed files with 339 additions and 265 deletions
--- a/src/components/Config.vue
+++ b/src/components/Config.vue
@@ -16,44 +16,55 @@
  <kuc-spinner :container="mainArea" v-show="loading" ref="spinner"></kuc-spinner>
 </template>
 <script setup lang="ts">
-import type { Setting } from '@/types/model';
+import type { Setting } from '@/types';
 import { useI18n } from 'vue-i18n';
 import type { Spinner } from 'kintone-ui-component';

 import { nextTick, onMounted, reactive, ref, shallowRef, watch } from 'vue';

-// i18n
+// 配置国际化
 const { t: $t } = useI18n();

+// 定义组件属性
 const props = defineProps<{ pluginId: string }>();
+
+// 响应式插件设置数据
 const setting: Setting = reactive({
  buttonName: '',
  message: '',
 });
-const error = ref('')
+
+const error = ref('');
 const loading = ref(false);

 const mainArea = shallowRef<HTMLElement | null>(null);
 const spinner = shallowRef<Spinner | null>(null);

 onMounted(async () => {
-  // 先将整体页面渲染出来，再弹出 spinner 进行数据读取
+  // 等待页面完全渲染后再显示加载状态，实现更平滑的用户体验
  nextTick(async () => {
    loading.value = true;
+    // 获取已保存的插件配置
    const savedSetting = kintone.plugin.app.getConfig(props.pluginId);
    setting.buttonName = savedSetting?.buttonName || $t('config.button.default');
    setting.message = savedSetting?.message || $t('config.message.default');
-    // 暂停 1s 用于展示 spinner Demo
+    // 模拟加载时间，展示 spinner 效果
    await new Promise((resolve) => setTimeout(resolve, 1000));
    loading.value = false;
  });
 });

-// 使用 loading 状态控制 spinner
+// 监听加载状态变化，控制 spinner 显示/隐藏
 watch(loading, (load) => {
  load ? spinner.value?.open() : spinner.value?.close();
 });

+/**
+ * 验证表单输入
+ * 检查必填字段是否已填写
+ * @param setting 要验证的设置对象
+ * @returns 验证是否通过
+ */
 function validate(setting: Setting): boolean {
  if (!setting.buttonName.trim()) {
    error.value = 'ボタン名を入力してください。';
@@ -62,19 +73,29 @@ function validate(setting: Setting): boolean {
  return true;
 }

+/**
+ * 保存配置设置
+ * 验证输入后将设置保存到插件配置中
+ */
 async function save() {
-  if(!validate(setting)){
+  // 先进行验证，如果验证失败则终止保存
+  if (!validate(setting)) {
    return;
  }
  loading.value = true;
-  // 暂停 1s 用于展示 spinner Demo
+  // 模拟保存时间，展示 spinner 效果
  await new Promise((resolve) => setTimeout(resolve, 1000));
+  // 保存配置到插件
  kintone.plugin.app.setConfig({
    buttonName: setting.buttonName,
    message: setting.message,
  });
 }

+/**
+ * 取消操作并返回插件列表
+ * 重定向到插件管理页面
+ */
 function cancel() {
  window.location.href = `../../${kintone.app.getId()}/plugin/`;
 }
--- a/src/components/basic/PluginInput.vue
+++ b/src/components/basic/PluginInput.vue
@@ -1,43 +1,48 @@
-<template>
-  <div class="kintoneplugin-input-container flex-row">
-    <plugin-label v-if="label" :label="label" :required-icon="requiredIcon" />
-    <kuc-text v-bind="textProps" :value="modelValue" @change="updateValue" />
-  </div>
-</template>
-
-<script setup lang="ts">
-import type { KucEvent } from '@/types/my-kintone';
-import type { TextProps, TextInputEventDetail } from 'kintone-ui-component/lib/text';
-import { defineProps, defineEmits, computed } from 'vue';
-
-// kuc 不支持 v-model 的写法，所以如果想要使用需要包装一下
-const props = withDefaults(defineProps<TextProps & {
-  modelValue: string;
-}>(), {
-  // boolean 的处理有点问题，这里手动重新定义
-  disabled: undefined,
-  requiredIcon: undefined,
-  visible: undefined
-});
-
-const emit = defineEmits<{
-  (e: 'update:modelValue', value: string): void;
-}>();
-
-const textProps = computed<TextProps>(() => {
-  const baseProps = {
-    ...props,
-    label: '', // 在 plugin-label 处显示 label，不传入 text
-    className: `kuc-text-input${props.className ? ` ${props.className}` : ''}`,
-  };
-
-  // 过滤掉所有值为 undefined 的属性
-  return Object.fromEntries(
-    Object.entries(baseProps).filter(([_, value]) => value !== undefined)
-  ) as TextProps;
-});
-
-const updateValue = ({ detail }: KucEvent<TextInputEventDetail>) => {
-  emit('update:modelValue', detail.value || '');
-};
-</script>
+<template>
+  <div class="kintoneplugin-input-container flex-row">
+    <plugin-label v-if="label" :label="label" :required-icon="requiredIcon" />
+    <kuc-text v-bind="textProps" :value="modelValue" @change="updateValue" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { KucEvent } from '@/types/my-kintone';
+import type { TextProps, TextInputEventDetail } from 'kintone-ui-component/lib/text';
+import { defineProps, defineEmits, computed } from 'vue';
+
+// KUC Text 组件不支持 v-model 语法，因此需要进行包装以支持双向绑定
+const props = withDefaults(defineProps<TextProps & {
+  modelValue: string;
+}>(), {
+  // 布尔值的默认值处理，设置为 undefined 表示未定义
+  disabled: undefined,
+  requiredIcon: undefined,
+  visible: undefined,
+});
+
+const emit = defineEmits<{
+  (e: 'update:modelValue', value: string): void;
+}>();
+
+/**
+ * 计算属性：生成传递给 KUC Text 组件的属性对象
+ * 过滤掉未定义的属性，避免传递无效值
+ */
+const textProps = computed<TextProps>(() => {
+  const baseProps = {
+    ...props,
+    label: '', // 标签由 plugin-label 组件显示，这里设置为空
+    className: `kuc-text-input${props.className ? ` ${props.className}` : ''}`, // 添加基础样式类
+  };
+
+  // 移除值为 undefined 的属性，确保只传递有效属性
+  return Object.fromEntries(Object.entries(baseProps).filter(([_, value]) => value !== undefined)) as TextProps;
+});
+
+/**
+ * 处理 v-model 事件
+ */
+const updateValue = ({ detail }: KucEvent<TextInputEventDetail>) => {
+  emit('update:modelValue', detail.value || '');
+};
+</script>
--- a/src/components/basic/PluginLabel.vue
+++ b/src/components/basic/PluginLabel.vue
@@ -1,15 +1,15 @@
-<template>
-  <div class="kintoneplugin-label">
-    <span>{{ label }}</span>
-    <span v-if="requiredIcon" class="kintoneplugin-label-required-icon">*</span>
-  </div>
-</template>
-
-<script setup lang="ts">
-import { defineProps } from 'vue';
-
-const props = defineProps<{
-  label: string;
-  requiredIcon?: boolean | undefined,
-}>();
+<template>
+  <div class="kintoneplugin-label">
+    <span>{{ label }}</span>
+    <span v-if="requiredIcon" class="kintoneplugin-label-required-icon">*</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { defineProps } from 'vue';
+
+const props = defineProps<{
+  label: string; // 标签文本内容
+  requiredIcon?: boolean; // 是否显示必填标记
+}>();
 </script>
--- a/src/i18n/index.ts
+++ b/src/i18n/index.ts
@@ -1,13 +1,27 @@
-import { createI18n } from 'vue-i18n';
-import ja from './lang/ja';
-import en from './lang/en';
-
-const i18n = createI18n({
-  legacy: false,
-  locale: kintone.getLoginUser().language || 'ja',
-  messages: {
-    ja,
-    en,
-  },
-});
-export default i18n;
+// 国际化配置
+// 配置 Vue I18n 实现多语言支持
+
+import { createI18n } from 'vue-i18n';
+
+// 动态导入语言文件
+const messages: Record<string, any> = {};
+
+const modules = import.meta.glob('./lang/*.ts', { eager: true });
+
+for (const path in modules) {
+  const match = path.match(/\.\/lang\/(\w+)\.ts$/);
+  if (match) {
+    const langCode = match[1];
+    const module = modules[path] as any;
+    messages[langCode] = module.default || module;
+  }
+}
+
+// 创建 i18n 实例配置
+const i18n = createI18n({
+  legacy: false, // 使用 Composition API 模式
+  locale: kintone.getLoginUser().language || 'ja',
+  messages,
+});
+
+export default i18n;
--- a/src/i18n/lang/en.ts
+++ b/src/i18n/lang/en.ts
@@ -1,14 +1,16 @@
-export default {
-  config: {
-    title: 'kintone Vue template',
-    desc: 'kintone Vue template for creating plugin',
-    button: {
-      label: 'button name',
-      default: 'button'
-    },
-    message: {
-      label: 'message',
-      default: ''
-    },
-  },
-};
+// 英语语言包配置
+// 包含配置页面相关的翻译文本
+export default {
+  config: {
+    title: 'kintone Vue template',
+    desc: 'kintone Vue template for creating plugin',
+    button: {
+      label: 'button name',
+      default: 'button',
+    },
+    message: {
+      label: 'message',
+      default: '',
+    },
+  },
+};
--- a/src/i18n/lang/ja.ts
+++ b/src/i18n/lang/ja.ts
@@ -1,14 +1,16 @@
-export default {
-  config: {
-    title: 'kintone Vue テンプレート',
-    desc: 'kintoneプラグイン作成用 Vue テンプレート',
-    button: {
-      label: 'ボタン名',
-      default: 'ボタン'
-    },
-    message: {
-      label: 'メッセージ',
-      default: ''
-    },
-  },
-};
+// 日语语言包配置
+// 包含配置页面相关的翻译文本
+export default {
+  config: {
+    title: 'kintone Vue テンプレート',
+    desc: 'kintoneプラグイン作成用 Vue テンプレート',
+    button: {
+      label: 'ボタン名',
+      default: 'ボタン',
+    },
+    message: {
+      label: 'メッセージ',
+      default: '',
+    },
+  },
+};
--- a/src/js/desktop.ts
+++ b/src/js/desktop.ts
@@ -1,35 +1,52 @@
-import type { Setting } from '@/types/model';
+import type { Setting } from '@/types';
+
 import { KintoneRestAPIClient } from '@kintone/rest-api-client';
+import { Button } from 'kintone-ui-component/lib/button';

 (function (PLUGIN_ID) {
  kintone.events.on('app.record.index.show', () => {
-    // App id
-    const appId = kintone.app.getId()?.toString();
-    if (!appId) return;
+    // 获取当前应用ID
+    const appIdNum = kintone.app.getId();
+    if (!appIdNum) {
+      return;
+    };
+    const appId = appIdNum.toString();

-    // get setting
+    // 从插件配置中读取设置信息
    const setting: Setting = kintone.plugin.app.getConfig(PLUGIN_ID);

-    // header space
+    // 检查按钮是否已存在，防止翻页时重复添加
+    const btnId = 'template-btn-id';
+    if (document.getElementById(btnId)) {
+      return;
+    };
+
+    // 获取 Header 容器元素
    const headerSpace = kintone.app.getHeaderMenuSpaceElement();
    if (!headerSpace) {
      throw new Error('このページではヘッダー要素が利用できません。');
    }

-    const btnId = 'template-btn-id';
-    // ボタン追加
-    if (document.getElementById(btnId)) return;
-    const button = new Kucs[KUC_VERSION].Button({
+    // 创建按钮
+    const button = new Button({
      text: setting.buttonName,
      type: 'submit',
      id: btnId,
    });
-    const client = new KintoneRestAPIClient();
    button.addEventListener('click', async () => {
-      const { plugins } = await client.app.getPlugins({
-        app: appId
-      })
-      alert(setting.message + "\n--------\n【Plugins】 " + plugins.map(p => p.name).join('、'));
+      try {
+        // 测试 KintoneRestAPIClient，显示所有已启用的插件名
+        const client = new KintoneRestAPIClient();
+        const { plugins } = await client.app.getPlugins({
+          app: appId,
+        });
+        const pluginsInfo = plugins.map((p) => p.name).join('、');
+
+        const message = setting.message + '\n--------\n【Plugins】 ' + pluginsInfo;
+        alert(message);
+      } catch (error) {
+        console.error('Failed to fetch plugins:', error);
+      }
    });
    headerSpace.appendChild(button);
  });
--- a/src/js/mobile.ts
+++ b/src/js/mobile.ts
@@ -1,35 +1,52 @@
-import type { Setting } from '@/types/model';
+import type { Setting } from '@/types';
+
 import { KintoneRestAPIClient } from '@kintone/rest-api-client';
+import { MobileButton } from 'kintone-ui-component/lib/mobile/button';

 (function (PLUGIN_ID) {
  kintone.events.on('mobile.app.record.index.show', () => {
-    // App id
-    const appId = kintone.mobile.app.getId()?.toString();
-    if (!appId) return;
+    // 获取当前应用ID
+    const appIdNum = kintone.mobile.app.getId();
+    if (!appIdNum) {
+      return;
+    };
+    const appId = appIdNum.toString();

-    // get setting
+    // 从插件配置中读取设置信息
    const setting: Setting = kintone.plugin.app.getConfig(PLUGIN_ID);

-    // header space
+    // 检查按钮是否已存在，防止翻页时重复添加
+    const btnId = 'template-btn-id';
+    if (document.getElementById(btnId)) {
+      return;
+    };
+
+    // 获取 Header 容器元素
    const headerSpace = kintone.mobile.app.getHeaderSpaceElement();
    if (!headerSpace) {
      throw new Error('このページではヘッダー要素が利用できません。');
    }

-    const btnId = 'template-btn-id';
-    // ボタン追加
-    if (document.getElementById(btnId)) return;
-    const button = new Kucs[KUC_VERSION].MobileButton({
+    // 创建按钮
+    const button = new MobileButton({
      text: setting.buttonName,
      type: 'submit',
      id: btnId,
    });
-    const client = new KintoneRestAPIClient();
    button.addEventListener('click', async () => {
-      const { plugins } = await client.app.getPlugins({
-        app: appId
-      })
-      alert(setting.message + "\n--------\n【Plugins】 " + plugins.map(p => p.name).join('、'));
+      try {
+        // 测试 KintoneRestAPIClient，显示所有已启用的插件名
+        const client = new KintoneRestAPIClient();
+        const { plugins } = await client.app.getPlugins({
+          app: appId,
+        });
+        const pluginsInfo = plugins.map((p) => p.name).join('、');
+
+        const message = setting.message + '\n--------\n【Plugins】 ' + pluginsInfo;
+        alert(message);
+      } catch (error) {
+        console.error('Failed to fetch plugins:', error);
+      }
    });
    headerSpace.appendChild(button);
  });
--- a/src/manifest.json
+++ b/src/manifest.json
@@ -5,7 +5,6 @@
  "type": "APP",
  "desktop": {
    "js": [
-      "js/kuc.min.js",
      "js/desktop.js"
    ],
    "css": [
@@ -40,7 +39,6 @@
  },
  "mobile": {
    "js": [
-      "js/kuc.min.js",
      "js/mobile.js"
    ],
    "css": [
--- a/src/types/index.d.ts
+++ b/src/types/index.d.ts
@@ -1,8 +1,3 @@
-declare global  {
-    const Kucs: {
-      [version: string]: any;
-    };
-    const KUC_VERSION: string;
-    const KUC_VERSION_DASHED: string;
-}
-export {};
+// 导出所有类型定义
+// 主要导出应用设置相关的类型接口
+export * from './model';
--- a/src/types/model.d.ts
+++ b/src/types/model.d.ts
@@ -1,4 +1,8 @@
-export interface Setting {
-  buttonName: string;
-  message: string;
-}
+// 插件设置接口定义
+// 描述用户可以在配置页面中设置的参数
+export interface Setting {
+  // 按钮显示名称，用户自定义按钮的文本
+  buttonName: string;
+  // 用户自定义的消息内容，在点击按钮时会显示此消息
+  message: string;
+}
--- a/src/types/my-kintone.d.ts
+++ b/src/types/my-kintone.d.ts
@@ -1,11 +1,17 @@
-import { KintoneFormFieldProperty } from '@kintone/rest-api-client';
-
-export interface KucEvent<T> {
-  detail: T;
-}
-
-export type SelectType =
-  | KintoneFormFieldProperty.CheckBox
-  | KintoneFormFieldProperty.RadioButton
-  | KintoneFormFieldProperty.Dropdown
-  | KintoneFormFieldProperty.MultiSelect;
+// 导入官方 REST API 客户端的类型定义
+import { KintoneFormFieldProperty } from '@kintone/rest-api-client';
+
+// KUC 组件事件类型定义
+// 定义 kintone UI 组件触发事件的结构
+export interface KucEvent<T> {
+  // 事件详情，包含组件传递的数据
+  detail: T;
+}
+
+// 选择类型字段联合类型
+// 定义支持的选择类字段类型，用于类型检查和推断
+export type SelectType =
+  | KintoneFormFieldProperty.CheckBox // 多选框字段
+  | KintoneFormFieldProperty.RadioButton // 单选按钮字段
+  | KintoneFormFieldProperty.Dropdown // 下拉选择字段
+  | KintoneFormFieldProperty.MultiSelect; // 多选下拉字段