在 2026 年 4 月 12 日的 kintone 定期更新中，新增了 4 個 JavaScript API，可在表格形式的記錄清單畫面中，透過程式動態地取得或設定各欄位的樣式。這組 API 分為「取得」與「設定」兩種操作，並各自提供 PC 版與行動版的對應方法。

API 介紹

這 4 個方法都會回傳 Promise，且僅能在「表格形式（List View）」的記錄清單畫面中使用。在不支援的畫面上呼叫時會 throw Error 物件。

🔗 官方文件連結（日文）：getRecordListStyle、setRecordListStyle

getRecordListStyle — 取得清單列表畫面的樣式

此方法不需要引數，會回傳一個 Promise，resolve 後得到目前清單列表中各欄位已套用的樣式設定物件。

const style = await kintone.app.getRecordListStyle()

回傳值結構

回傳物件包含 header（陣列）和 body（陣列）兩個屬性。header 對應表格標頭列，body 對應各記錄行。

header 中每個元素的結構如下：

{
    columnType: "FIELD",         // "FIELD"（欄位列）或 "ACTION"（操作 UI 列）
    column: "文字列__1行_",       // 欄位代碼或操作 UI 識別名稱
    content: {                   // 內容的樣式
        color: "#ffff00",
        fontWeight: "bold",
        textDecoration: "underline"
    },
    background: {                // 背景的樣式
        backgroundColor: "#0000ff"
    }
}

body 中每個元素以 recordId 標識記錄，並在 style 陣列中列出該行各欄位的樣式。body 的 content 比 header 多出 backgroundColor 和 borderColor 兩個屬性（僅 PC 版）：

{
    recordId: 1,
    style: [{
        columnType: "FIELD",
        column: "文字列__1行_",
        content: {
            backgroundColor: "#ffff00",  // ※僅 PC 版
            color: "DEFAULT",
            fontWeight: "bold",
            textDecoration: "underline",
            borderColor: "#ffff00"       // ※僅 PC 版
        },
        background: {
            backgroundColor: "#0000ff"
        }
    }]
}

回傳值的特性

• 回傳所有可設定的屬性：即使透過 setRecordListStyle 只設定了部分屬性，getRecordListStyle 也會回傳所有可設定的屬性。未被設定的屬性值會以 "DEFAULT" 表示。
• 屬性值一律以小寫回傳：即使透過 setRecordListStyle 以大寫設定值（例如 "BOLD"），回傳時也會轉為小寫（"bold"）。唯一的例外是 "DEFAULT"，固定以大寫回傳。
• 對於樣式指定會被忽略的欄位（如 Rich Text Editor 的 content），由於等同於未設定樣式，各屬性皆回傳 "DEFAULT"。
• header[] 和 body[].style[] 按照表格中由左至右的欄位順序排列。
• body[] 按照表格中由上至下的記錄順序排列。

錯誤處理

在清單列表的初次渲染完成前呼叫此方法時，Promise 會被 reject，並附帶一個包含「本 API 無法在畫面載入中執行，請在畫面顯示完成後再執行」旨意的錯誤訊息。

setRecordListStyle — 設定清單列表畫面的樣式

透過傳入 config 物件，可以對表格的「標頭（header）」和「本體（body）」分別指定樣式。這是一種一時性的外觀變更，不會影響實際的欄位值。當 app.record.index.show（或行動版的 mobile.app.record.index.show）事件觸發時（即表格重新渲染時），所有已套用的樣式會被解除。

引數：config（必填）

config 物件的結構如下：

const config = {
    header: [{ // 標頭的樣式設定（選填）
        columnType: "FIELD",    // "FIELD"（欄位列）或 "ACTION"（操作 UI 列）。省略時預設為 "FIELD"
        column: "欄位代碼",      // columnType 為 "FIELD" 時指定欄位代碼；
                                // columnType 為 "ACTION" 時指定 "OPEN_DETAIL" 或 "RECORD_ACTIONS"（※僅 PC 版）
        content: {              // 內容的樣式（選填）
            color: "#ff0000",           // 文字顏色
            fontWeight: "bold",         // 字體粗細："normal" 或 "bold"
            textDecoration: "underline" // 文字裝飾："none"、"underline" 或 "line-through"
        },
        background: {           // 背景的樣式（選填）
            backgroundColor: "#0000ff"  // 背景顏色
        }
    }],
    body: [{ // 本體（各記錄行）的樣式設定（選填）
        recordId: 1,
        style: [{
            columnType: "FIELD",
            column: "欄位代碼",
            content: {
                backgroundColor: "#ffff00", // 內容背景色（※僅 PC 版，且僅在行內編輯中生效）
                color: "#ff0000",
                fontWeight: "bold",
                textDecoration: "underline",
                borderColor: "#ffff00"      // 邊框顏色（※僅 PC 版，且僅在行內編輯中生效）
            },
            background: {
                backgroundColor: "#0000ff"
            }
        }]
    }]
}

await kintone.app.setRecordListStyle(config)

顏色值與樣式值的規則

• 顏色相關屬性（backgroundColor、color、borderColor）僅接受 6 位數的十六進位色碼格式（如 #ffffff）。
• 字體粗細 fontWeight 僅接受 "normal" 或 "bold"。
• 字體裝飾 textDecoration 僅接受 "none"、"underline" 或 "line-through"。

※指定不符合規則的值時，該屬性會被忽略而不套用。

※樣式值的比對依循 CSS 規範，不區分大小寫（case insensitive）。但 "DEFAULT" 是 kintone 固有的特殊值，僅接受大寫。

使用 "DEFAULT" 重設樣式

"DEFAULT" 可在多個層級使用，用來解除已套用的樣式：

套用優先順序

header[]、body[]、body[].style[] 陣列中的元素會按照順序依次套用。如果同一對象被指定了多次，後面的設定會覆蓋前面的設定。例如，對同一個欄位先設定 fontWeight: "bold"，再設定 fontWeight: "normal"，最終結果為 "normal"。

限制

以下情況下，指定的樣式會被忽略而不產生作用：

• columnType 為 "ACTION" 時，content 的指定會被忽略（header/body 皆同）
• 未顯示在清單列表中的欄位、因存取權限不可見的欄位、不支援的欄位
• 表格形式清單列表的初次渲染完成前執行時
• 規格中未定義的屬性名稱（如 background.borderColor）

不支援的欄位類型：

• 關聯記錄
• 群組
• 分隔線
• 標籤
• 空白欄
• 子表格（PC版中，樣式僅套用至開關按鈕所在的儲存格，展開後的子表格不受影響）

以下欄位類型即使指定了 content 也會被忽略：

• 文字編輯方塊
• 子表格

以下情況下，content.borderColor 和 content.backgroundColor 會被忽略：

• 行動版畫面
• PC 版中的欄位： 選項按鈕、核取方塊

PC 版特有：行內編輯相關行為

• content.backgroundColor 和 content.borderColor 僅在行內編輯中才會生效。
• 以下欄位的 content 僅在非行內編輯狀態下才會生效（因為行內編輯時這些欄位為不可編輯狀態）：記錄號碼、建立者、建立時間、更新者、更新時間、計算、設為自動計算的單行文字方塊、類別、狀態、處理者、附件、Lookup
• 行內編輯中處於 disabled 狀態的欄位（例如透過 JS API disabled、無編輯權限、Lookup 複製目標等），content 樣式不會套用，但其他可套用的樣式（如 background）仍然有效。當 disabled 狀態解除時，先前指定的 content 樣式會重新套用。

錯誤處理

當傳入的引數不符合方法的介面規範時（例如缺少必填項目、型別不符、值不正確），Promise 會被 reject，並附帶說明正確呼叫方式的錯誤訊息。

PC 版與行動版的差異

好的，以下是範例程式碼的段落和結語的草稿：

應用範例

此範例以一個簡易的任務管理應用程式為例，展示如何搭配 getRecordListStyle 和 setRecordListStyle 來實現「根據記錄內容動態變更清單列表外觀」的效果。

假設應用程式中有以下欄位：

程式會根據記錄內容，對清單列表套用以下樣式：

• task 欄位的文字設為粗體
• done 欄位的值為 "N"（未完成）時，文字顏色設為橘紅色（#ff4500）
• priority 欄位依據優先度設定不同的背景色："1" 為淺紅色（#f08080）、"2" 為金色（#ffd700）、"3" 為淺藍色（#afeeee）

效果如下圖：

範例程式碼

(() => {
  'use strict'

  kintone.events.on('app.record.index.show', async event => {
    try {
      // 透過 event 物件取得記錄資料，並轉成以 id 為 key 的物件，方便後續比對
      const { records } = event
      const recordsMap = {}
      records.forEach(record => {
        const id = record.$id.value
        recordsMap[id] = {
          done: record.done.value,
          priority: record.priority.value
        }
      })

      // 呼叫 getRecordListStyle API，取得目前的列表樣式
      const listStyle = await kintone.app.getRecordListStyle()
      // 遍歷 header columns 取得 index，減少後續比對的次數
      const columnsIndex = {}
      listStyle.header.forEach((header, index) => {
        columnsIndex[header.column] = index
      })

      // 遍歷 body 的每一列，根據記錄資料設定樣式
      listStyle.body.forEach(row => {
        const id = row.recordId
        if (!recordsMap[id]) return

        row.style[columnsIndex.task].content.fontWeight = 'bold'

        if (recordsMap[id].done === 'N') {
          row.style[columnsIndex.done].content.color = '#ff4500'
        }
        
        if (recordsMap[id].priority === '1') {
          row.style[columnsIndex.priority].background.backgroundColor = '#f08080'
        } else if (recordsMap[id].priority === '2') {
          row.style[columnsIndex.priority].background.backgroundColor = '#ffd700'
        } else if (recordsMap[id].priority === '3') {
          row.style[columnsIndex.priority].background.backgroundColor = '#afeeee'
        }
      })

      // 呼叫 setRecordListStyle API，將修改後的樣式套用到列表
      await kintone.app.setRecordListStyle(listStyle)
      
    } catch (error) {
      console.error(error)
    }

    return event
  })

})()

程式碼解說

這段程式碼在 app.record.index.show 事件中執行，也就是表格形式的記錄列表每次渲染完成時觸發。整體流程可以分為四個階段：

1. 準備記錄資料
2. 取得現有樣式
3. 修改樣式
4. 套用樣式

準備記錄資料

從 event.records 中取出當前頁面上的所有記錄，並以記錄 ID 為 key 建立 recordsMap 物件。這樣做的目的是在後續遍歷樣式物件時，能夠透過 recordId 快速查找對應記錄的欄位值，而不需要每次都在陣列中搜尋。

取得現有樣式

呼叫 getRecordListStyle() 取得目前的樣式物件。
這裡有一個值得注意的技巧：程式先遍歷 header 陣列，建立了 columnsIndex 物件，將欄位代碼對應到其在陣列中的索引位置。由於 header[] 和 body[].style[] 的欄位排列順序一致（都是表格中由左至右），因此可以利用 header 建立的索引值，直接以 row.style[columnsIndex.task] 的方式精準定位到 body 中對應欄位的樣式物件，避免在每一列中都要遍歷 style 陣列去尋找目標欄位。

修改樣式

遍歷 body 中的每一列，根據 recordsMap 中對應記錄的欄位值，套用前述的樣式規則。

套用樣式

呼叫 setRecordListStyle(listStyle)，將修改後的樣式物件整體傳入，一次套用所有變更。這裡直接將 getRecordListStyle 回傳的物件修改後再傳回 setRecordListStyle，是一個簡潔而實用的模式——因為回傳物件的結構本身就符合 setRecordListStyle 所需的 config 格式。

結語

getRecordListStyle 和 setRecordListStyle 這組 API，讓開發者不再需要透過直接操作 DOM 來變更清單列表的外觀。透過 kintone 官方提供的介面來設定樣式，不僅寫法更簡潔，也不必擔心因 kintone 的 DOM 結構變更而導致自訂功能失效。

在實際運用上，有幾點值得留意。首先，由於 app.record.index.show 事件觸發時會重設所有樣式，因此樣式的設定邏輯應該放在該事件的處理函式中，確保每次畫面重新渲染時都能正確套用。其次，本文範例中的樣式判斷條件是寫死在程式碼中的，但在實務上，可以考慮將條件規則（例如「哪個欄位值對應哪個顏色」）存放在另一個 kintone 應用中作為設定檔，透過 REST API 讀取後再套用；或者進一步將功能開發為外掛，將設定存放在外掛的設定畫面中，讓管理者無需接觸程式碼就能自行調整配色與條件。

另外，官方文件中也提到，某些裝飾設定的組合可能會造成輕微的顯示錯位。此外，隨著產品未來的更新，各屬性所對應的具體裝飾範圍等細節也可能有所變動。建議在套用樣式後實際確認顯示效果，並在 kintone 版本更新時留意相關的變更資訊。