ScopeMatrix

scope-matrix

范围矩阵 · 允许/禁止两个语义对立的模式桶 + 底部「有效范围小结」写成人话(这类配置最易想错的正是「禁止优先」与「允许为空≠全部禁止」) + suggestions 候选点选填入 + 只读/受控双态 · 权限白名单/同步范围/CI 触发路径 · 不内置 glob 校验(各家方言差异大·猜错比不猜更糟)

用法

任务范围配置

两个语义对立的桶。底部小结会把「最终有效范围」写成人话——这类配置最容易想错的就是空白名单与优先级。

允许1 条

留空表示不启用白名单，此时只受「禁止」约束

src/**

禁止1 条

命中即拒绝，优先级高于「允许」

**/node_modules/**

先看「禁止」（1 条）：命中即拒绝；未命中的再看「允许」（1 条），命中才允许。

tsx

<ScopeMatrix
  allow={scope.allow}
  deny={scope.deny}
  onChange={setScope}
  suggestions={derivedFromProject}
/>

带语法校验

组件不内置模式语法校验——glob / 正则 / ant 风格差异很大，猜错比不猜更糟。需要就传 validate。

允许0 条

留空表示不启用白名单，此时只受「禁止」约束

未设置（不启用白名单）

禁止0 条

命中即拒绝，优先级高于「允许」

未设置

当前未设置任何范围限制。

tsx

<ScopeMatrix
  allow={allow}
  deny={deny}
  onChange={onChange}
  validate={(p) => (p.startsWith("/") ? "请用相对模式，不要绝对路径" : null)}
/>

只读回顾

不给 onChange 即为只读，用于审计视图或历史配置回看。

允许2 条

留空表示不启用白名单，此时只受「禁止」约束

packages/ui/**
docs/**

禁止2 条

命中即拒绝，优先级高于「允许」

**/dist/**
**/node_modules/**

先看「禁止」（2 条）：命中即拒绝；未命中的再看「允许」（2 条），命中才允许。

tsx

<ScopeMatrix allow={record.allow} deny={record.deny} />

什么时候用

权限 / 白名单配置
任务或作业的可改动范围
路由守卫、文件同步范围、CI 触发路径

什么时候不用

场景	用什么	为什么
从固定候选池搬运	`Transfer`	候选是封闭集合，用户只能选不能造
自由输入的一维标签	`TagInput`	没有「两个对立的桶」这层语义

用法

tsx

import { ScopeMatrix } from "@hulianui/ui";

const [scope, setScope] = useState({ allow: ["src/**"], deny: ["**/dist/**"] });

<ScopeMatrix
  allow={scope.allow}
  deny={scope.deny}
  onChange={setScope}
  suggestions={derivedFromProject}
/>

Props

名称	类型	默认	说明
`allow`	`string[]`	—	允许列表；空数组 = 不启用白名单
`deny`	`string[]`	—	禁止列表
`onChange`	`(next: { allow, deny }) => void`	—	不给则为只读
`suggestions`	`string[]`	`[]`	候选模式，点击填入输入框
`readOnly`	`boolean`	`false`	强制只读
`validate`	`(pattern) => string \| null`	—	返回错误文案表示非法
`allowLabel` / `denyLabel`	`ReactNode`	`"允许"` / `"禁止"`	桶标题
`allowHint` / `denyHint`	`ReactNode`	见默认值	桶下方说明
`placeholder`	`string`	`"输入模式后回车"`	输入占位符

设计取舍

底部小结是这个组件存在的主要理由。 允许/禁止两个列表谁都会做，但这类配置有两个极易想错的点：

禁止优先于允许 —— 同时命中时以禁止为准。
允许为空 ≠ 全部禁止 —— 而是「不启用白名单」，只受禁止列表约束。

第 2 条写反的后果是配好之后一切都被拦，用户会以为工具坏了。与其指望人读文档，不如让界面随时把当前配置的实际效果写成一句话。

不内置模式语法校验。 glob / 正则 / ant 风格 / 自定义 DSL 差异很大，组件猜错比不猜更糟。需要校验就传 validate。

候选点击只填入不提交。 候选往往需要在填入后微调（改个层级、加个后缀），直接提交会逼用户先加后删。

Playground

只读显示候选

允许1 条

留空表示不启用白名单，此时只受「禁止」约束

src/**

禁止1 条

命中即拒绝，优先级高于「允许」

**/node_modules/**

先看「禁止」（1 条）：命中即拒绝；未命中的再看「允许」（1 条），命中才允许。

<ScopeMatrix
  allow={scope.allow}
  deny={scope.deny}
  onChange={setScope}
  suggestions={derivedFromProject}
/>

用法

任务范围配置

两个语义对立的桶。底部小结会把「最终有效范围」写成人话——这类配置最容易想错的就是空白名单与优先级。

允许1 条

留空表示不启用白名单，此时只受「禁止」约束

src/**

禁止1 条

命中即拒绝，优先级高于「允许」

**/node_modules/**

先看「禁止」（1 条）：命中即拒绝；未命中的再看「允许」（1 条），命中才允许。

tsx

<ScopeMatrix
  allow={scope.allow}
  deny={scope.deny}
  onChange={setScope}
  suggestions={derivedFromProject}
/>

带语法校验

组件不内置模式语法校验——glob / 正则 / ant 风格差异很大，猜错比不猜更糟。需要就传 validate。

允许0 条

留空表示不启用白名单，此时只受「禁止」约束

未设置（不启用白名单）

禁止0 条

命中即拒绝，优先级高于「允许」

未设置

当前未设置任何范围限制。

tsx

<ScopeMatrix
  allow={allow}
  deny={deny}
  onChange={onChange}
  validate={(p) => (p.startsWith("/") ? "请用相对模式，不要绝对路径" : null)}
/>

只读回顾

不给 onChange 即为只读，用于审计视图或历史配置回看。

允许2 条

留空表示不启用白名单，此时只受「禁止」约束

packages/ui/**
docs/**

禁止2 条

命中即拒绝，优先级高于「允许」

**/dist/**
**/node_modules/**

先看「禁止」（2 条）：命中即拒绝；未命中的再看「允许」（2 条），命中才允许。

tsx

<ScopeMatrix allow={record.allow} deny={record.deny} />

场景

用什么

为什么

从固定候选池搬运

Transfer

候选是封闭集合，用户只能选不能造

自由输入的一维标签

TagInput

没有「两个对立的桶」这层语义

import { ScopeMatrix } from "@hulianui/ui"; const [scope, setScope] = useState({ allow: ["src/**"], deny: ["**/dist/**"] }); <ScopeMatrix allow={scope.allow} deny={scope.deny} onChange={setScope} suggestions={derivedFromProject} />

Props

名称	类型	默认	说明
`allow`	`string[]`	—	允许列表；空数组 = 不启用白名单
`deny`	`string[]`	—	禁止列表
`onChange`	`(next: { allow, deny }) => void`	—	不给则为只读
`suggestions`	`string[]`	`[]`	候选模式，点击填入输入框
`readOnly`	`boolean`	`false`	强制只读
`validate`	`(pattern) => string \| null`	—	返回错误文案表示非法
`allowLabel` / `denyLabel`	`ReactNode`	`"允许"` / `"禁止"`	桶标题
`allowHint` / `denyHint`	`ReactNode`	见默认值	桶下方说明
`placeholder`	`string`	`"输入模式后回车"`	输入占位符

设计取舍

底部小结是这个组件存在的主要理由。 允许/禁止两个列表谁都会做，但这类配置有两个极易想错的点：

禁止优先于允许 —— 同时命中时以禁止为准。

允许为空 ≠ 全部禁止 —— 而是「不启用白名单」，只受禁止列表约束。

第 2 条写反的后果是配好之后一切都被拦，用户会以为工具坏了。与其指望人读文档，不如让界面随时把当前配置的实际效果写成一句话。

不内置模式语法校验。 glob / 正则 / ant 风格 / 自定义 DSL 差异很大，组件猜错比不猜更糟。需要校验就传 validate。

候选点击只填入不提交。 候选往往需要在填入后微调（改个层级、加个后缀），直接提交会逼用户先加后删。

Playground

只读显示候选

允许1 条

留空表示不启用白名单，此时只受「禁止」约束

src/**

禁止1 条

命中即拒绝，优先级高于「允许」

**/node_modules/**

先看「禁止」（1 条）：命中即拒绝；未命中的再看「允许」（1 条），命中才允许。

<ScopeMatrix
  allow={scope.allow}
  deny={scope.deny}
  onChange={setScope}
  suggestions={derivedFromProject}
/>